News for hackers. Stuff that matters.
Re:Important non-programming skills for programmers by darkhorse13 on Thursday September 24, 2020 @11:04AM (#24579272)
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/

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.