
Improving documentation of open source software - felicianotech
https://www.futurice.com/blog/improving-documentation-of-open-source-software/
======
ken
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."

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

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

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

~~~
rambojazz
What's this? An advertisement?

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

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

~~~
gav
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?

~~~
andrewingram
\- why might I not want to use it?

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

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

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

~~~
ken
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. :-)

