Posts

underlap, 1 month ago

@clobrano That's a great question. Some suggestions:

1. Find and read good design docs.
2. Ask people to provide feedback on the design docs you write.
3. Search the web for checklists of topics to include.
4. Add your own topics relevant to the area you work in.
5. Work on your general writing skills, e.g. read "The Elements of Style" by Strunk and White.

1/2

henrikjernevad, 1 month ago

@clobrano I find it helpful to think about what you want to achieve by writing the documentation. Who is it for? What do you want them to understand? Then think about what you need to say to do that.

Try to put yourself in the shoes of the reader. If they did not know anything except that which you have written, would it make sense? Have you introduced all terms before using them? Do you consistently use the same words for the same concepts? Is each paragraph conceptually coherent?