4 ms·

> Why does nobody do this in their readmes normally? They just let you look into their code and tell you "now figure it all out yourself". I think it's worth p

by JadeNB 5y ago

> Why does nobody do this in their readmes normally? They just let you look into their code and tell you "now figure it all out yourself". I think it's worth praising this repo without knocking others. Open source authors have no obligation to their users; if they don't have the time to, or just don't care to, so organise their READMEs, then they need not. In fact, if it's sufficiently important, for much open-source software anyone else can do it, and submit a patch.

nerdponx 5y ago
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.

by JadeNB 5y ago

nerdponx 5y ago

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.