Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

All of the above. But as someone who writes documentation let me add, most programmers are bad writers.

To write good documentation you need to mix technical reference (the easy part) with user reference. The latter requires you to imagine where the user is at, and take them to where they understand. This is hard to do, and requires well, skills.

So a culture of documentation is great, but quality matters as much as quantity. Clarity, completeness and coherence are all legs of the stool.



Certainly writing is a skill that many programmers are not good at.

However IMO an easy trap to fall into is to start documenting without a bigger understanding of the audience and the purpose of the doc.

A good way to start is to identify which of the 4 types of documentation you are working on.

https://nick.groenen.me/posts/the-4-types-of-technical-docum...

Personally I find it very easy to put too much explanation in the wrong places.


This issue around poor writing skills is something that I've thought/worried about for a while. At some level of seniority (the more junior the better IMO) we expect developers to write design docs. The inability to communicate clearly in those documents is a huge problem. Oftentimes misunderstandings and ambiguities are cleared up at design review, but then never reintegrated into the document, leaving two artifacts, the implementation and the design doc. These obviously drift over time, maintaining correspondence is hard. But when one only ambiguously described the other from the get go, then the documentation is broken. This too is technical debt.

If you are fortunate, you can write code in an organization which has a high code quality bar, uses consistent styles etc. But it is rare (vanishingly so I nearly 30 years experience) to find the same bar applied to the design docs.


You also need technical writers.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: