I'm a junior dev in a large company and after a few small projects I got an assignment to write a technical document for the system my team develops and supports. The document will then be used internally between developers, especially newcomers.
The system is made of out of the box enterprise solutions, custom software, a bunch of APIs, numerous SQL and server instances, legacy business code, web apps etc. There are bits and pieces of documentation for some of the parts but there is no complete document where all of the ins and outs of the system are explained in a readable and understandable way.
I'll have help from senior devs and architects but this is mainly my task. Are there any articles, tutorials, books to read and can you give me advice how to start, what to look for and what to avoid before I jump into this rabbit hole?
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.
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.
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.
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.
Sorry if this looks like a stream-of-consciousness. It sort of is. I hope you can find some of it useful.