Write docs like you write (good) code
It’s fairly well acknowledged that you should write simple and easy to read code – you write code for others, not to showcase how smart you are. The same should go for documents you write, whether these are design docs, one pagers or anything else.
You should write docs only if they are useful. Your performance as a software engineer boils down to your impact. If you write a doc that nobody needs, you are essentially wasting your time (that you could spend doing something else). A common mistake I see from junior engineers is that they write long design docs for minor changes because they think this is what senior engineers do. My 2 cents is that bad senior engineers write docs about everything – good ones will write just enough docs to maximize their team impact.
You should write docs tailored to your audience. Your readers (especially your leadership, tech leads etc.) have very little time – spend the time to sharpen your doc. Keep your docs short and crisp. Provide only the details or if you really need more details, leave them in an appendix. The most common mistake I see from junior engineers is writing code in a design doc, a security section when there are no security concerns, a legal section when the legal team isn’t going to review their doc etc.
You add a date on your docs and keep them up to date when relevant – if they are out of date, call it out and point to the new one. This is similar to how you would mark some API deprecated if people should be using a new one.
For what it’s worth, I write a lot of one pagers and very little long docs – I can count one one hand the number of design docs I wrote that were more than 5 pages I think.
What tips do you have about writing good docs?