3 ms·

Over time I've noticed that a lot of software developers aren't good documentation writers. I'm not saying this is good or bad, but it is a statement I believe

by brwr 11y ago

Over time I've noticed that a lot of software developers aren't good documentation writers. I'm not saying this is good or bad, but it is a statement I believe to be true. With that said, what advantages are there to removing the bottleneck of "I updated the docs, please everyone check before release and send me your comments"? To me, personally, letting anyone update the docs without review sounds like a recipe for trouble.

imrehg 11y ago
Yeah, very few people are good documentation writers. After writing up a lot of maker projects I found that I like to do docs, and that makes me also more demanding regarding the quality of the docs I need to feedback on. It would be great if people would put more time in it to become better, and another reason why I like sort-of self-documenting tools (e.g. Rust, where documentation is taken seriously from the beginning of the project). I didn't mean everyone can update the docs, rather send feedback by patch/pull request of actual changes instead of writing in email with words that "Rewrite header 1 to be X, add label Y to figure 2, and add date into footer". Currently bloody Word Docs and PDFs are sent around twice a day for "please reply with your comments", and things get lost between emails, changes that were applied before disappear because someone edited the wrong version of the Doc, or exported into PDF in the wrong way... All in all, changes shouldn't happen in email text, IMHO. Whether anyone can edit the docs - I'd actually like to see that (even if I haven't said that originally). Currently even the people who are charged with maintaining the docs update it only when pushed, I think in most places you'd be lucky if anyone touches it. On the other hand, an empowered team where anyone can access improve on things is a very different feeling, that's what creates successful stuff, IMHO. And with version control failure is cheap and easy to fix, so there's very little downside. Think of large public projects like OpenStreetMap or the Embedded Linux Wiki at http://elinux.org http://elinux.org It works out pretty well for them with no big trouble, and they literally let everyone change things (not just project members).

by brwr 11y ago

imrehg 11y ago

Yeah, very few people are good documentation writers. After writing up a lot of maker projects I found that I like to do docs, and that makes me also more demanding regarding the quality of the docs I need to feedback on. It would be great if people would put more time in it to become better, and another reason why I like sort-of self-documenting tools (e.g. Rust, where documentation is taken seriously from the beginning of the project). I didn't mean everyone can update the docs, rather send feedback by patch/pull request of actual changes instead of writing in email with words that "Rewrite header 1 to be X, add label Y to figure 2, and add date into footer". Currently bloody Word Docs and PDFs are sent around twice a day for "please reply with your comments", and things get lost between emails, changes that were applied before disappear because someone edited the wrong version of the Doc, or exported into PDF in the wrong way... All in all, changes shouldn't happen in email text, IMHO. Whether anyone can edit the docs - I'd actually like to see that (even if I haven't said that originally). Currently even the people who are charged with maintaining the docs update it only when pushed, I think in most places you'd be lucky if anyone touches it. On the other hand, an empowered team where anyone can access improve on things is a very different feeling, that's what creates successful stuff, IMHO. And with version control failure is cheap and easy to fix, so there's very little downside. Think of large public projects like OpenStreetMap or the Embedded Linux Wiki at http://elinux.org http://elinux.org It works out pretty well for them with no big trouble, and they literally let everyone change things (not just project members).