4 ms·
Writing documentation for your code/library/framework/project should be another one of these skills. I have written a lot of documentation for a project [1] rec
by darkhorse13 6y ago
Writing documentation for your code/library/framework/project should be another one of these skills. I have written a lot of documentation for a project [1] recently, and it has made me realize the importance of this skill. It is often overlooked by programmers, myself included, as before this project, I never wrote proper documentation.
Sure, you can get technical writers to do it for you if you have a big team, but a lot of small, open source projects suffer from the lack of proper documentation.
[1] https://www.gethalfmoon.com/docs/introduction/ https://www.gethalfmoon.com/docs/introduction/
- robocop556 6y agoI agree. Out of curiosity, what was this project?
- darkhorse13 6y agoI edited the parent comment with a link to the docs.
- rawburt 6y agoHalfmoon look real nice, as does the documentation. Kudos
- agumonkey 6y agoon a similar note I've always been shocked by linux distros wikis. you can have: - near nothing, good luck - debian, ultra structured, .. hard to digest / boring - gentoo / arch, barely structured, just enough content to get the gist, yet precise, and a lot more tips for funsies. this is an art
- cashewchoo 6y agofwiw I find the arch approach the best tradeoff of practical and useful. Usually when I go to a distro wiki, I'm not really going there to learn in-depth what it is. I'm going there because I have a problem or a question. So having low-structure (easy to contribute to), high-signal (too much low-interest clutter info tends to contribute to documentation decay) tidbits seems to work out well. I particularly like that if I have an issue, and I figure it out, I can just pop a quick line in there. h4:"Issues snafucating while running nvidia proprietary driver". Body: "you get this error message. <snip>. This is due to <snip>. Run this command to fix it." And it's already at the quality that people expect.
- agumonkey 6y agoYes and this tells a few things about what a good piece of software is. Arch is not easy but it doesn't bloat you, it gives you a few pieces to play, when you have an issue there's a paragraph for you. Software is often documented as if it was a integral part of the program, but it's wrong on the human level I believe.
- ezoe 6y agoEven though I have never use Arch, the most helpful texts are always comes from and intended to Arch. That tells something.
- kps 6y agoGood documentation is hard but, in the current jargon, it is a value multiplier — or rather, poor or missing documentation is a value multiplier with a factor ≪1. Good documentation also needs ‘testing’ by someone who is not already familiar with the content.