I actually like writing documentation, even if I'm not great at it yet, but I struggle to be able to do this well for other people's software. I feel that project documentation, to be done well, has to be part of the project itself.<p>Half the time I start writing documentation for a feature I've built myself, I go back and rework the design based on what I learned from trying to document it. It's rather enlightening to write "Here's how to do this thing that you'll do 100 times a day...", and then discover to your horror that it takes 14 steps. Oops.<p>And when you try to document the <i>why</i> and <i>how</i> of most open-source projects, it very often comes down to "historical accident" and "it's like some other ancient system you've probably never used either". There's a lot of features where I'd just write "This next dialog box is useless, so just hit return", or "This thing you have to type is completely nuts, so just memorize this nonsense".<p>I believe that's why third-party documentation (O'Reilly books, The Missing Manual series, etc) is so successful. It's a lot easier to write (tactfully) "This is dumb, so here's how you get past it", than to go back and fix the feature. And nobody wants to write documentation about their own software that says "Yeah, I know this thing you have to do here is dumb, but hey, it's only a 1.0 so please don't hurt me."
Love docs? Check out <a href="https://www.writethedocs.org" rel="nofollow">https://www.writethedocs.org</a> — conferences in 3 continents and meetups around the world. Also a slack community for more real-time docs talk.
Hey! Original author here, excited to see open source documentation brought up in Hacker News.<p>I feel like documentation in general is a topic we developers don't talk about enough and it's often cast aside as a "we'll do it if there's time" and I think we all know there's never gonna be "time".<p>If you wanna set up similar things with your colleagues or local community, feel free to hit me up (email in bio) or ask here and I'm more than happy to share ideas and how we made it happen.
In addition to docs, I’d also add evangelism as often missing. For a project to be successful, someone fronting the project and engaging with a potential community on how it could be used. Call it “sales” or “marketing” even, but open source projects need it as much as proprietary products...
Isn't it that what we need is an authoritative wiki?<p>With one or more pages per piece of software, depending on complexity.<p>Eg: when you have to know how to cut videos from time1 to time2 using ffmpeg but not much time for reading man pages, such a wiki with tutorials would be of great help.<p>For ffmpeg, of course, you can find some blog, but not in case of all software.