getting internal dev doc right
TRANSCRIPT
![Page 1: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/1.jpg)
Getting internal dev doc right
Not something you learn in a day.
© Elisa R. Sawyer, MS 2000-2017 [email protected]
![Page 2: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/2.jpg)
© Elisa R. Sawyer, MS 2000-2017 [email protected]
toscano-kalahari-meerkat-statues
Beyond the checklists
Dev doc writers must think inside and outside simultaneously.
![Page 3: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/3.jpg)
A profession influences
spoken language.
Language encapsulates
culture.
© Elisa R. Sawyer, MS 2000-2017 [email protected]
Graphic credited to BB O'Riley
![Page 4: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/4.jpg)
Language and belonging
Internal to a team or group:
• Knows cool group vocabulary.
• Knows in-jokes.
• Intuits their role or function.
External to a team or group:
• Needs to learn vocabulary.
• Needs humor to alleviate stress.
• Often uncertain role or function.
© Elisa R. Sawyer, MS 2000-2017 [email protected]
![Page 5: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/5.jpg)
“We made it comfortable here.”
© Elisa R. Sawyer, MS 2000-2017 [email protected]
Photo from http://www.newsbiscuit.com/2017/03/14/rabbit-hole-leads-to-ancient-rabbit-warren/
![Page 6: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/6.jpg)
“My team watches out for me.”
http://www.burrard-lucas.com/gallery/wildlife/africa/botswana/meerkats.html
© Elisa R. Sawyer, MS 2000-2017 [email protected]
![Page 7: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/7.jpg)
Techinfo cycles
© Elisa R. Sawyer, MS 2000-2017 [email protected]
analysis
synthesis publish
receive feedback
![Page 10: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/10.jpg)
© Elisa R. Sawyer, MS 2000-2017 [email protected]
Writing is re-writing
Give a software developer audience:
• Why.
• Who, what, where, when, how.
• Mostly active and imperative voice.
• Instructions that build confidence.
![Page 11: Getting internal Dev Doc Right](https://reader033.vdocuments.mx/reader033/viewer/2022051710/5a6ce9f27f8b9ab3418b47a3/html5/thumbnails/11.jpg)
Continue to ask:
What is the users’ point of view?
We don’t always get it right in the first draft.
© Elisa R. Sawyer, MS 2000-2017 [email protected]