Getting internal Dev Doc Right

Getting internal dev doc right

Not something you learn in a day.

© Elisa R. Sawyer, MS 2000-2017 [email protected]


toscano-kalahari-meerkat-statues

Beyond the checklists

Dev doc writers must think inside and outside simultaneously.

A profession influences

spoken language.

Language encapsulates

culture.


Graphic credited to BB O'Riley

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.


“We made it comfortable here.”


Photo from http://www.newsbiscuit.com/2017/03/14/rabbit-hole-leads-to-ancient-rabbit-warren/

“My team watches out for me.”

http://www.burrard-lucas.com/gallery/wildlife/africa/botswana/meerkats.html


Techinfo cycles


analysis

synthesis publish

receive feedback

Documentarians are translators.


Professional babel

• Good

• Bad

• Ugly



Writing is re-writing

Give a software developer audience:

• Why.

• Who, what, where, when, how.

• Mostly active and imperative voice.

• Instructions that build confidence.

Continue to ask:

What is the users’ point of view?

We don’t always get it right in the first draft.


Date post:	28-Jan-2018
Category:	Technology
Upload:	elisa-sawyer
View:	114 times
Download:	0 times

Getting internal Dev Doc Right

Technology