Comment by ignoramous

2 days ago

Extending the Interior Design metaphor, the context of what's being designed and for who, that is, the doc archetype (manual, tutorial/guide, reference, recipies/demos/samples, audience-specific), is the first important part to get right.

https://github.com/google/opendocs/tree/main/project_archety...

> technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally

  why do people read docs ... because they want to achieve something ... you need to work out what problem your reader is trying to solve.

  If Dusty wants to put their degree up on the wall, they might want to consult some documentation about how to do it. The documentation Dusty needs to do this would probably not be called "How to Choose a Drill". The documentation Dusty needs is "How to Hang a Picture".