@ -116,6 +116,35 @@ Message in console printed by Bridle to welcome users - source: booktwo.org
- often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts
- often documentation doesn't offer entry points for beginners, or a sense of direction, this esp a problem with hypertexts
```
```
- who writes code documentation tends to assume a certain kind of reader, to talk a specific language, to refer to a particular context
sections
__expert reader, formerly educated reader__
takes for granted the technical level of the reader,
takes for granted a specific lexicon,
relates with external sources without referring to them
__male! developer often addressed as he/him__
- within a particular cultural niche! western
- dude
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
Writing code documentation is tricky because requires some degree of astral projection. Who's writing is asked to leave their body and describe code from a different perspective. From the point of view of someone else. Unlearn what seems to be obvious and be generous with future readers.
