Skip to content

re: What makes maintaining documentation difficult? VIEW POST


I wrote a series of articles about this issue. I think the main problem is that we're not writing documentation for our current ourselves. We're writing it for some abstract user (ourselves in the future or a random user). A bit like the Pomodoro technique, I think we can simulate an emergency effect and become concerned right now by our documentation, by in a very regular way testing how a new developer can handle the project just thanks to written documentation.


This is a really good point to keep in mind, one that I know I need to get better at. The most helpful documentation out there really does focus on showing new users unfamiliar with the full framework how to solve a problem with the framework, rather than just showing off all its many features without much guidance. I'll definitely be checking out those articles later today, but do you have any practical, easily rememberable tips that help you put yourself into that mindset?


The final article in my series especially talks about this process. To sum it up: frequently find a developer that is not familiar with your code, and ask them to 1/ install the project, 2/ dive into the code (understand the structure and how things work).
Then the dev writes an issue on the repository, summarizing every problem they found in the documentation. And if they can't install the project because of a problem, then they can even stop there and directly write an issue.
This process can be called a Bus Factor Review. If done frequently (every 2 weeks?) it can be very fast (because it's incremental) and very useful to 1/ keep the doc in sync and 2/ to easily have a summary of the obscure things in your project.

Of course this applies in the context of a company, but I guess we could even create a community to do so, with personal projects :).

code of conduct - report abuse