Improving documentation of open source software | Hacker News Reader

Improving documentation of open source software

futurice.com

77 pointsfelicianotech19 comments

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.

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.

And when you try to document the why and how 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".

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."

I really like your point about third party documentation. I've written the "this is dumb" line before but that's usually on a forum not a doc.

I totally agree with you. It requires good understanding of the project but also it's beneficial to know the pitfalls and decisions made or left unmade that ended up shaping the project. That's why I encourage developers to make documenting (just like testing) a part of feature development and bug fixing rather than an additional hurdle.

I like Tom Preston-Werner's Readme Driven Development[0] approach. Instead of leaving documentation as something that happens as an afterthought, start with it. I've tried it a few times with my smaller hobby projects and it has helped me a lot.

Similar to TDD, RDD allows me to design the API before I ever write the actual code. I also get to design the build process, contribution model and bunch of other things up front.

When it comes to the "why" of projects, I like DHH's Doctrine document[1] on Ruby on Rails. I wish more software projects would feature a similar document since that answers a lot of questions, especially about the opinionated decisions.

[0] http://tom.preston-werner.com/2010/08/23/readme-driven-devel... [1] https://rubyonrails.org/doctrine/

On my personal projects, I like writing the documentation.

What I specially like is having the documentation live right next to the software, typically in the same repository. That way, you have a clear incentive to update it when doing change in the code, and it's also clearly versioned with the software (1000 thanks to read the doc), you can also treat gap in the documentation as bugs.

However, writing good documentation can be really hard. As the developer, you are, at the same time, the best and worst placed person to document. Best because you know exactly how the software is supposed to work, and worst, because you might miss documenting things that seems obvious to you, but not to the user.

Lastly, as a developer, it can be hard to take a step back, and give a higher level view of the documentation, not diving directly into too much details.

For that, having reviewing from an external eye, and feedback from users can be really helpful.

> However, writing good documentation can be really hard. As the developer, you are, at the same time, the best and worst placed person to document. Best because you know exactly how the software is supposed to work, and worst, because you might miss documenting things that seems obvious to you, but not to the user.

This is an important point! That's why I think it's so valuable to constantly have discussions with the users of your products. Not only to improve the products themselves but the documentation and the on-boarding process.

Love docs? Check out https://www.writethedocs.org — conferences in 3 continents and meetups around the world. Also a slack community for more real-time docs talk.

What's this? An advertisement?

Hey! Original author here, excited to see open source documentation brought up in Hacker News.

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".

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...

There's a list of things that should be right there on the project homepage:

- What is this project?

- Who is the intended audience?

- Why would I use it?

- How does it compare to other projects?

- Where should I go for help/support, i.e. where is the mailing list/forums/etc.

- How can I get up and running with the minimum of effort?

- why might I not want to use it?

I really appreciated the "drawbacks" link on the sidebar at migadu.com. If you know there are use cases that don't fit your goals, admit them up front.

A lot of proprietary projects don't even do that. The project homepage is targeted at managers so to a programmer it often comes across as meaningless marketing blurb (IMHO).

Evangelism is needed if adoption is a goal, which is far from a given even for proprietary products.

I cannot agree more.

It’s simultaneously something that’s incredibly important, but also weirdly under-valued.

Isn't it that what we need is an authoritative wiki?

With one or more pages per piece of software, depending on complexity.

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.

For ffmpeg, of course, you can find some blog, but not in case of all software.

That's cool. We interact with as many communities as possible but sometimes it's hard to know if people find our documentation useful

Have you talked with people using your tools and asked them? Unfortunately people will rarely send unsolicited good feedback to tools they enjoy so it's important to chat with your users.

Here's what worked for me (inadvertently). Brag about how good your documentation is on your product home page. Then people will go out of their way to volunteer all the ways in which it is not optimal for them. :-)

Reply on news.ycombinator.com