Re:Making world-class docs takes effort
by simonw on Monday September 06, 2021 @02:55PM
(#28436776)
Absolutely agree. The documentation relating to the code needs to live with that code.
The single biggest problem I see with documentation is lack of trust: if people in an organization learn that the documentation is often out-of-date they will stop consulting it, which means the will also stop writing it.
The fix for this is for the documentation to live alongside the code, and for code reviews to take that into account: if an implementation change leaves the documentation out-of-date, point that out in the code review and refuse to merge it until the documentation has been updated as part of the same change!
The single biggest problem I see with documentation is lack of trust: if people in an organization learn that the documentation is often out-of-date they will stop consulting it, which means the will also stop writing it.
The fix for this is for the documentation to live alongside the code, and for code reviews to take that into account: if an implementation change leaves the documentation out-of-date, point that out in the code review and refuse to merge it until the documentation has been updated as part of the same change!