3 ms·

This isn't just about open source. Developers on internal projects should do this too, but don't.

• bluGill 5y ago
  Have you ever tried to write useful documentation? As a programmer you are far to close to the code. You assume things are obvious that are not, while going into great detail describing things that are obvious (or maybe not obvious, but only rarely interesting and so should be documented in a deeper link not the main documentation). Or worse because you have to document it you document the code lines (++i; // increment i by one). This is a hard problem. I try to make an effort, but too often I get it wrong.
  • nerdponx 5y ago
    Of course I have. And of course I recognize that writing good docs is difficult. I am not talking about the difficulty of writing high-quality explanatory prose. I'm talking about expanding what people consider standard practice, to include a bullet-point description of how the files in the project are laid out. You don't need to be a good writer in order to do this. That said, just because something is hard doesn't mean it's not a skill that can be learned. Not everyone has the same attitude for writing (much like programming), but generally I believe that "most people can be taught most things to a basic level of competence", and I do not think documentation writing is exempt from that principle. There is no reason why the skill of writing halfway-decent documentation should not be taught in programming courses.