I've been struggling with writing documentation for a piece of software that I've been working on during the past months.
The task is so boring that I just can't put any effort into it. I've never wrote any documentation before, and always struggled with writing descriptive content. The last time I did it was for my internship report and it was so daunting.
I've been trying to polish up my skills to write technical and end-user documentation. At this point, I feel like it might be useful to start learning from other people's work and filter out what makes them helpful.
What are some examples of great documentation? What makes great documentation for you?
I have had to deal with lots of different methodologies about documentation practices and what i found is that the best documentation is code. Self documenting code and tests usually stay up to date and are harder to overlook.
We have technical writers who work in conjunction with developers to author the documentation. I don't know what tool they use.
However, since you say you want to get better at writing docs, let me offer some perspectives based on a user of documentation.
1) Write to all of your target audience. For example if your product is targeted at both technical and non-technical people, then write the documentation in such a way that non-technical folks can understand it. Don't just write for the technical people.
2) If possible, write documentation around several 'how do I do XYZ task'? My experience has been that people tend to turn to documentation when they want to execute a specific task and they tend to search for those phrases
3) As much as is possible, include examples. This tends to remove ambiguities.
Can you please share the lessons learned in the courses about writing documentation or perhaps recommend some courses/materials?
At my place we have an eternal struggle in “level”. We have some very high over docs, then ADR for specific decisions. At the lowest level we have the api documentation which we find most people don’t read. And then we have some tutorials. Every time I read our documentation it feels very inadequate of conveying all our knowledge and intentions.
Writing _good_ documentation absolutely can be just as tiring as creating the thing being documented. It's quite common to not particularly value documentation quality and be happy with a mess of words churned out with little thought because at least it exists, but ensuring that it's accurate, covers all of the little details, and is organized well requires some careful thought and editing processes.
With a formal division between "deep thought" work and "easy" work, I'd be inclined to churn out a rough draft of documentation in the second time box but then spend at least as much time as that in the first time box cleaning it up.
It seems useful to get a sense of how different organizations handle documentation in the real world. I'm curious whether your org uses the following types of documentation (or any others) and how they manage it, with whatever details you can give:
-Developer setup
-Developer best practices & style
-Product documentation
-Project documentation
-Docblocks/doc strings
-Inline comments
More importantly, what are the habits that your org encourages around documentation?
reply