Re:Important non-programming skills for programmers
by agumonkey on Thursday September 24, 2020 @12:38PM
(#24580499)
on 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
Re:Important non-programming skills for programmers
by ezoe on Thursday September 24, 2020 @01:39PM
(#24581206)
Even though I have never use Arch, the most helpful texts are always comes from and intended to Arch. That tells something.
Re:Important non-programming skills for programmers
by cashewchoo on Thursday September 24, 2020 @01:15PM
(#24580958)
fwiw 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.
Re:Important non-programming skills for programmers
by agumonkey on Thursday September 24, 2020 @03:18PM
(#24582443)
Yes 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.
Re:Important non-programming skills for programmers
by kps on Thursday September 24, 2020 @02:25PM
(#24581800)
Good 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.
Re:Important non-programming skills for programmers
by rawburt on Thursday September 24, 2020 @11:22AM
(#24579452)
Halfmoon look real nice, as does the documentation. Kudos
Re:Important non-programming skills for programmers
by robocop556 on Thursday September 24, 2020 @11:09AM
(#24579314)
I agree. Out of curiosity, what was this project?
Re:Important non-programming skills for programmers
by darkhorse13 on Thursday September 24, 2020 @11:15AM
(#24579372)
I edited the parent comment with a link to the docs.
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/