I write a lot of documentation. I do it not because others ask, but because I genuinely believe it is going to be helpful to someone at some point, and anticipate this need. So when Bobby from marketing asks about a feature, or Kate the junior dev can’t wrap her head about some algorithm, hey, I got them covered!<p>So I think this mindset is the first thing you need in order to get going. It will inspire you to write more and better.<p>Secondly, my practical advice is the following:
divide your doc in sections. Plan them out beforehand by writing just titles and subtitles. See how they fit together, if their sequence makes sense. Rearrange them until they convey a clear story. Usually you might want to have three macro-sections: 1. Introduction - what is the document about, who is it indended for, and why it was developed. This helps set expectations right off the bat. You can also describe the big-picture goals of the system/feature. What is it used for. What are the main use cases.
2. System/Feature Overview: here you can describe the big-boxes architecture, the main components (apps, servers, middleware, db, whatever), what they do, and how they work together. Describe communication protocols and standards followed. Describe functionalities the system provides. You can follow up on the use cases you mentioned in part 1 and show how the system delivers them.
3. Technical Details/Implementation Choices: depending on the audience of your doc, you might want to document non-obvious design choices. This is also where might want to describe expected inputs and outputs. If it’s an API, describe the routes, accepted methods, paylods. Provide actual examples, as many as you can. Describe the data model.<p>Then as you follow this trace, you might find out you wrote a lot about a certain topic. Depending on the level of detail you want to achieve, break it down in smaller sub-sections, or move parts over to section 3.<p>As for the writing style, you might want a prose with short sentences and easy language. Make sure to explain stuff thoroughly and not take anything for granted. Everything that looks damn obvious today, won’t be 6 months from now.<p>Sorry if this looks like a stream-of-consciousness. It sort of is. I hope you can find some of it useful.