
Things People Hate about Your Open Source Docs - Baustin
http://blog.smartbear.com/careers/13-things-people-hate-about-your-open-source-docs/
======
cobrausn
_Of course, your examples shouldn’t just be brief two-line snippets. As Rich
Bowen of the Apache project puts it, “One correct, functional, tested,
commented example trumps a page of prose, every time.”_

If HN allowed signatures, that quote would be mine. I grok libraries and other
people's code so much faster when I have a good working example, and the mere
existence of that example makes me 10x more likely to use the lib (or, when I
have no other option, 10x more likely to complain less).

~~~
Apreche
This is 100% true. I am constantly frustrated by incomplete code examples in
documentation. The one thing in particular that bothers me the most are when
Python snippets don't show the import statements.

do_magic(param, other_param)

Where do I import do_magic from?!?!

~~~
Cyranix
Same thing in Java -- if there's a class named something commonplace like
"Transaction" or "Connection", it's going to be pretty critical to understand
whose implementation that refers to.

~~~
kamjam
Same in .Net, although Resharper
([http://www.jetbrains.com/resharper/](http://www.jetbrains.com/resharper/))
has made my life a lot easier by giving me much better import/using
suggestions, although not 100% foolproof.

------
zdw
Manpages used to be the defacto best source of information, but sometime in
the last 15 years they went from great to a hit and miss shambles.

I write this up to GNU's "info" being preferred by some programs, but then
that not being installed properly or at all on many system, and people hating
manpage syntax, often with good reason.

That said, some systems pay a lot of attention to this. OpenBSD's mandoc is a
great example of a modernization of the manpage system, and their manpages are
second to none: [http://www.openbsd.org/papers/bsdcan11-mandoc-
openbsd.html](http://www.openbsd.org/papers/bsdcan11-mandoc-openbsd.html)

~~~
kyrias
Wait, there's programs that use info? o.O

~~~
coldpie
Oh yeah. 'man cp' from my Arch Linux machine:

\---

SEE ALSO

The full documentation for cp is maintained as a Texinfo manual. If the info
and cp programs are properly installed at your site, the command

    
    
                  info coreutils 'cp invocation'
    

should give you access to the complete manual.

\---

I ran that 'info' command and promptly ran the one emacs command I have
memorized: C-x C-c

:)

~~~
m-r-a-m
I recently switched to Emacs and started learning it by going through the
tutorial (C-h t). Near the end of the tutorial, it refers you to the Emacs
manual which uses info (C-h r). After going to the manual I had no idea how to
navigate, so I ran the info tutorial (h). I don't really have a point, but I
think it's funny that I had to run the a tutorial to get help.

------
coldpie
I think I've seen every imaginable "bar" object have every possible "foo"
action performed on it. This is the most frustrating thing I find in example
code. Yes, I know your library is generalized and will work with any type of
object. Please give me a concrete example of where your library might be
useful, so I can easily visualize your library's role in my head. I can
generalize it myself, thank you very much.

------
vacri
The author forgot 'Stale docs'. Once the docs are written, 'that task is done'
and new features or changes aren't documented...

------
psychometry
I hate incomplete docs the most. Most OSS developers would agree that if
you're adding a feature to a repository, then you should also be adding a
test. There should also be an expectation that you should be adding docs, too.

------
oalders
Having offline docs can be quite handy. A few years ago a friend and I put
together an iOS app called iCPAN, so that we could have offline Perl docs at
our disposal. This kind of thing is particularly helpful because perldoc
doesn't work on modules which you have not yet installed. It's also great if
you want to read Perl docs on the subway, but I'll admit that's not everyone's
cup of tea. :)

~~~
SubMachinePun
Now I feel almost obliged to mention having read EmberJS docs while on the
crapper. Thanks.

------
rmason
The biggest sin is not explaining what the project does and the problem that
it solves.

I've had people complain to me that no one is using their great open source
project. I complain that you don't explain what it does or why its great.

They answer that all you have to do is read the code. I try to diplomatically
tell them that there aren't enough hours in anyone's life to read all the code
on Github.

The project is not ready to upload if you haven't finished the documentation.

------
duwease
Amen. Just amen.

I've worked on at least a couple of open source projects now that have a
strong and active core team building everything, and who are talented enough
to write great code. But when it's almost time to launch v1.0, the call always
goes around: "Who's willing to write the documentation?" And the response is
always silence. Documenting just isn't as "fun" as coding, I guess.

But it is, arguably, at least _as_ important if not _more_ , if your goal
involves popularity. I recommend open source software projects to groups who
are looking for an open source solution, and the ones with an active support
community and good documentation, but some sloppy code, win every time over
the expertly coded masterpiece that can only really be understood by stepping
through the code in a debugger.

------
doktrin
It's occurred to individuals smarter than myself that projects rise and fall
on the strength of their documentation, almost as much as that of their code.

For example, see Django vs. Turbogears or Pylons.

Documentation matters, a lot, despite its relative unsexyness.

------
coherentpony
The great thing about open source documentation is that you can write a patch
and attempt to fix it. It would probably take less time to clone a repository
and submit a pull request than it did for the author to write that article.

~~~
hamburglar
Yes, instead of writing an excellent article that explains some principles
that could help hundreds or thousands of open source authors improve their
projects, he should have taken the approach of shutting up and fixing every
one of those projects himself.

Open source should not be about efficiency! It should be about never pointing
out anything wrong unless you're willing to change it yourself! Down with
feedback! We hate feedback! We're open source authors and we don't have to
take it anymore!

------
gleb_bahmutov
Lack of examples is the major problem, since it is hard to maintain examples
in sync with the code. I created tool
[https://npmjs.org/package/xplain](https://npmjs.org/package/xplain) that
transforms unit tests (javascript) into human readable examples in the API
docs. Makes lots of up-to-date examples in the docs possible without any
penalty.

------
unsignedint
Not necessary docs, but what I have been observing in a lot of OSS is an
absence of one-liner explaining what the project exactly is; especially ones
without descriptive project name.

Good "feature list" would probably help, but it's just a pain when reading
through 5 paragraphs down only to find that it's not what I think it is.

~~~
daemonl
You mean you can't figure it out from an alphabetical list of command line
flags? Oh, wait, neither can I.

------
lignuist
Very good thoughts. At least there should be a README. I think about creating
a template for READMEs.

~~~
beat
That would be a good open source project!

~~~
bergie
This project sounds sort of promising: [https://github.com/bevry/readme-
utils](https://github.com/bevry/readme-utils)

------
incision
> _Lack of realistic examples_

So true.

I've frequently had the impression that writers are plain missing the point -
with the most dense, clever self-satisfying examples as opposed to verbose,
simple and instructive.

------
egonschiele
> 5\. Lack of screenshots

So many GUI libraries do this and it's always frustrating. If you're a GUI
library, when I get to your website, the first thing I see should be a
screenshot.

------
yaddayadda
Things People Hate about Your Docs (there, corrected).

As @coherentpony stated, at least with open source others can pick up the
slack.

------
derleth
The biggest thing I'd like to see more often are usable example applications.
Not just snippets of example code, but working applications which show off
some aspect of what your library or tool is intended to do in a complete form.
And keep in mind that people looking to see if they want to use your stuff see
buggy applications, that reflects on _everything_.

There's a joke to the effect of "Every working Unix program derives from
'Hello, world!' in K&R." There's a similar joke about Windows programs and the
first example program in Petzold's book. Write your library or tool's version
of a 'Hello, world!', make it tasteful, and keep it working across bug fixes
and version changes. That's the testbed; that's what people new to your work
will modify stepwise into whatever they really want to build.

The second thing I wish I saw more often are "Theory Of Operation" documents,
which document how the developers expect their stuff to be used.

Who is the intended audience? What other stuff do the developers expect the
intended audience has seen? If it's a library, what do the developers expect
the core of a client application to look like? If it's a tool, what do the
developers expect its most common mode of interaction to be? It shouldn't be a
listing of what each function does, but something that gives an idea of what
the developers think the core functionality is would be very helpful.

Get into the head of your users. What would you want to know going in, if you
were a user?

