
WTFM - Write The Freaking Manual - Floopsy
http://www.floopsy.com/post/32453280184/w-t-f-m-write-the-freaking-manual
======
crazygringo
I would upvote this a million times if I could. I'm one of the kinds of people
who wants to read the entire reference manual, front to back, before using a
programming language, library, etc. I want to make sure I know exactly what it
does, the proper way to use it, and what it doesn't do. This is both so I can
make an informed choice about the technology, and it saves a huge amount of
time in the long run.

But it seems like there's a big trend now to just "get things out there" and
that good documentation isn't "cool" anymore, kind of like braces in syntax.

Examples of good docs: PHP, jQuery, MySQL. (The first two sites include user
comments too, which make things even _more_ useful.)

Examples of terrible docs: Python, CoffeeScript (the worst)

I can at least understand insufficient docs for pre-1.0 versions when the
implementation is changing constantly, but when something has been around for
more than a year, it's just inexcusable.

I don't want a "getting started" guide that gives a bunch of examples. I don't
want to type in the console to find out what methods an object has.

I want a friggin' reference manual, that includes (as applicable) syntax
rules, exact rules governing whitespace, orders of operations, all functions,
all parameters, parameters passed to a callback (why are these forgotten so
often?), default values, flag values, all possible return values, specific
exceptions that can be thrown, what input parameters result in undefined
behavior.

Really, it's just not that hard. It may be grunt work, but if you'd rather
make your users waste a cumulative 25,000+ hours figuring things out, rather
than you spending 100 hours of your own explaining things, I just can't have
respect for your product, no matter how otherwise amazing it is.

~~~
reinhardt
You're in a small minority, what you want and don't want is irrelevant. It's
2012, nobody reads dry reference manuals cover to cover, nevermind doing so
before firing up a shell window and an editor.

Reference manuals are still nice to have of course for clarifying edge cases
and solving language lawyer disputes. However claiming that they are a
superior learning and time-saving tool than the learn-by-example techniques is
way out of touch with how most people actually learn.

~~~
demewmew
People learn in a variety of different ways, and I'm also a developer who
always prefers a reference manual over learn-by-example techniques. You may
not be one of those developers, but that doesn't mean we don't exist. I
imagine there are plenty of people who don't learn by the reference manual but
would prefer to have it available - if it was available - as well.

------
exDM69
When it comes to open source work, which I mostly do on my own, limited time
and don't get paid for, I have a choice. I can spend time writing code or
writing documentation. The former I enjoy very much, the latter I don't like
at all. Guess which I am going to pick.

The times when I've actually ended up writing some docs, I don't think anyone
has ever read them. And writing the docs is just the beginning, they have to
be maintained too. Out of date docs are perhaps worse than no docs at all.

I don't read docs either, because they tend to be out of date. Formal
specifications are an exception. But when it comes to open source, I just tend
to read the source because it's never out of date and tells the whole story.
What was obvious to writer of the doc isn't obvious to me and vice versa.

The first person who comes to me asking for documentation to my projects
volunteers to write them, like it or not.

~~~
Swizec
Conversely, I don't even use open source software that doesn't have a simple
README on Github showing me plentiful examples on how to use the damn library.

Sorry, if you don't have documentation, even a little bit, you're just not
worth my time. There are at least two other libraries out there with better
documentation. The fact they might be worse software doesn't even matter
because all I'm looking for is a _solution_.

~~~
exDM69
GitHub READMEs are an excellent compromise. Doing more detailed docs are quite
a lot of effort (that is better spent coding), especially to projects that are
at an early stage.

Projects which are an early stage (like most of my projects) should mostly try
to attract potential contributors, not just consumers/end-users so it's not
unreasonable to require would-be users/contributors to walk the extra mile and
actually read (at least parts of) the source. I do that even for projects that
are well established with docs if I intend to depend on them.

If there actually were libs that are well documented and do the same thing, I
wouldn't have started the projects I did but contribute to the existing
projects instead. This may not be true for all kinds of projects.

~~~
rgbrgb
There's a double standard here. You want developers to contribute to your
project despite the lack of documentation but you require that libraries you
contribute to are well documented.

~~~
exDM69
> ...but you require that libraries you contribute to are well documented.

You misread me. I almost never read the docs because they suck more often than
not. I start from example and test source code and almost always end up
reading parts or most of the source code.

~~~
rgbrgb
> If there actually were libs that are well documented and do the same
> thing...

I thought you were implying that you required libs you contribute to to be
well documented.

------
jackalope
And please, WTFV isn't enough. I don't have time to watch or search through a
40 minute video to find out how to set a few configuration options. Text is
king when it comes to documentation. Videos are fine for tutorial purposes,
but I need a solid reference that's well indexed and searchable.

~~~
nathan_long
Video is also a poor replacement for text because it is MUCH more laborious to
create and update, so it probably won't be updated.

If someone were willing to make a video, writing text should be a given.

------
smoyer
There are actually many open-source projects that have excellent documentation
and there are many that don't have documentation at all. I think there's
actually a shortage of projects with simply adequate documentation.

Many open-source projects also allow you to contribute to the documentation,
so I don't think you should criticize projects you're actually using but
rather that you should help maintain the documentation (even if it's just bug
reports).

If you have an open-source project with very few users, you'll often find that
you can't get traction simply because when people can't figure out how to use
your software, they'll go elsewhere. Want fame and (maybe) fortune? Make your
project useable.

------
dredmorbius
I fully endorse this. Coming from a sysadmins / devopps perspective,
documentation is key to providing a reliable, dependable, available, scalable
service. And dramatically improving the quality of my life.

 _How_ that documentation is written also matters. _A lot_.

Much proprietary documentation is also crap, for numerous reasons. Marketing
having too much say is key (every reference to a Trademarked(r) Name(tm)
Phrase(c) is both fully expanded and badged. Might keep the marketers and
lawyers happy, but it's hell to read. Descriptions are vacuous to the point of
idiocy ("More magic: select this option to enable more magic") -- tells me
absolutely _nothing_ not inherent in the control, and in particular, fails to
tell me what the _effect_ of enabling "more magic" is (feature name changed,
but this construct is all too common in docs).

Usage notes and examples are mandatory.

As much as Free Software docs are pilloried, I still find that they tend to
compare favorably with non-free docs.

Noted here:
[https://plus.google.com/104092656004159577193/posts/bLaDaXNe...](https://plus.google.com/104092656004159577193/posts/bLaDaXNeJu4)

~~~
incision
Coming from the same perspective, I agree completely.

Software pushers all seem to give the same puzzled look when I ask to see
their full docs before evaluating their product.

It's exactly as you describe, if the documentation isn't sufficient for me to
learn everything I could possibly need and likely want to know about how
things work - I can't confidently design, build, scale or support it.

Documentation in the "Enterprise" world seems almost intentionally bad, as if
to force customers into professional services and support contracts for
products which lack the proper design to be sold as full on SaaS.

------
tsahyt
Yes, this. I'm looking at you, freedesktop.org... PulseAudio documentation is
poor. Considering it doesn't really work out of the box on half the systems
out there that's pretty bad. fontconfig docs are some of the worst I've seen
in a long time. In general, I feel dizzy when I find a link with
"freedesktop.org" in it labeled "docs"...

There are plenty of other examples. Seriously, documentation is extremely
important. Especially if you're relying on config files, _document them
properly_.

------
leeoniya
i'm currently writing a tutorial/manual for a library i wrote several months
ago. the library took maybe 1 month to write and now the tutorial has taken 3
months. creating examples, illustrations, demos, determining and writing the
sections in a sensical, progressive order takes a _long_ time (epecially when
it's done in your free time) :(, but without it, the project is DOA and no one
will use it.

also, writing a tutorial has helped me refactor and decouple parts of the lib
a few times to simplify and hone the API to something much more elegant than
it was in the beginning. sometimes i feel like Git could have used the same
kind of process to create an much more refined, wart-free API also.

------
jiggy2011
To be honest, good documentation is more or less my #1 criteria for choosing
which library to use.

Not only is it much easier to work with something that is well documented but
I also find as a general rule well documented projects seem to be maintained
for a lot longer.

------
aidenn0
I think after you write a manual for your first few projects and clearly less
than 1% of your users read it, it gets hard to motivate yourself to write
another manual.

~~~
dredmorbius
The advantage of documentation isn't that users read it _before_ asking
questions.

It's that you answer questions by pointing at the relevant section of the
docs.

If that section doesn't exist, it's a good practice to see that it does
(either write it yourself, have another contributor write it, or encourage the
person asking the question to submit a doc).

------
norswap
I couldn't agree more. The lack of good documentation is a plague which is not
emphasized quite enough. To me it is as (or even more) important than writing
tests: debugging code is easy in comparison to figuring out what it is
supposed to do in the first place.

------
fellars
Any pointers on how to make it easier to wtfm? If anyone out there actually
enjoys writing documentation I'd be willing to pay for some help and guidance
on a rather large commercial open source project that is in need of some tlc
regarding documentation

~~~
takluyver
In the Python world, readthedocs.org has made writing docs easier - it takes
care of rebuilding documentation each time you commit. It's implemented in
Python, and most popular with the Python community, but it can be used for
other languages as well.

------
brudgers
The root of this issue is that writing documentation is not something that
really good hackers like to do...these days [1].

And it's damn sure not something that good writers are interested in...unless
they are paid. Paying good writers to write documentation is not a core
competency of the FOSS community, nor part of its ethos.[2]

[1] These days being the age of the internet and languages implementing
brogrammar. People like McCarthy and Knuth wrote their own documentation to a
dead tree publication standard, not a rough draft of a Wiki standard.

[2] Erlang and Go aren't going to give the world another RPG or PG writing
passionately about their wonders.

~~~
pnathan
One thing I've done a few times is to help out just by writing docs for open
source projects.

I know it's a drag. I know it's not that much fun. But it massively -
MASSIVELY - improves the project's value, especially if it's low on the totem
pole.

~~~
brudgers
But of course, your profile lists lisp.

~~~
pnathan
I beg pardon, what do you mean by that?

~~~
brudgers
Lisp has a literary tradition stronger than other languages. See Richard P.
Gabriel, or Paul Graham for that matter. Python and Cpp may have polemics, but
none as useful as _Let Over Lambda_.

------
trotsky
Reminds me of the old expression: "fast, cheap, good. pick two."

When we were largely buying shrink wrapped software they almost all came with
decent sized manuals (quality varied, of course). He tagged the post with a
bunch of open source projects, which has almost never been an area of good
manuals. It's very uncommon for "scratching your own itch" to lead to
comprehensive documentation for obvious reasons. Developers seldom write the
extensive manuals, tech writers do.

~~~
Zelphyr
I think his point was more that clearly the developers want people to use what
they built. So taking that extra step and writing good documentation would
only help ensure that people used their software. Not doing so actually hurts
their chances. Not doing so and expecting SOMEONE ELSE to do it is just dumb.

------
todd3834
I agree with the author, I have found myself in similar situations and it is
frustrating. However, I also think programmers need to RTFSC (SC == Source
Code)

------
orangethirty
And please, run your source through a tool like doxygen for me to get a better
understanding of how your software is built and designed. I've been advising a
startup that is facing issues with documentation not being available for the
platform they chose to use. The platform looks good, and the code is fairly
readable, but there is no documentation. To complicate things, the platform is
under active development and things change weekly (if not daily). The
solution? The startup is looking to have their application written in another
platform. All we need is for you to explain how stuff works in a language that
even a grilled cheese sandwich will understand.

------
ternaryoperator
And while we're at it: Javadoc is not a substitute for writing documentation.

------
orangethirty
There is a big need here waiting to be satisfied. Documentation is very
important and a lot of projects are losing traction due not having the basics
or it being done poorly. I'm actually working with a new platform by writing
their documentation for them. Why would I do that? I have a talent for it, and
it allows me to offer a service other full-stack engineers won't even think
about doing. Writing documentation as a job is a great way to improve my
engineering skills. If I can explain it to people, then I definitely know how
something works.

------
blahedo
Relevant, I think:

<http://www.ginandtacos.com/2012/09/24/tab-a-slot-b>

In it, the author speculates that one of the reasons that kids have such a
hard time following directions is that they never learn to read them, because
nothing comes with directions anymore (you just "figure it out"). It's sort of
the dark side of ubiquitous discoverable UI.

------
incision
This is one of the reasons I consider my Safari subscription indispensable.

It provides immediate access to generally well-written and structured
documentation and instruction covering a wide range of topics. The one
downside would be the obvious lack of bleeding edge topics as those books have
yet to be written.

------
jobu
Good documentation is _really hard_ to do, but it's also one of the most
important things for any product or project. If no one uses what you make then
it truly is useless, and you will never get people to use something unless
they can figure out how.

------
mmariani
Here's a great approach to solve this issue. Also, it's a good talk too.

[http://blip.tv/pycon-us-
videos-2009-2010-2011/pycon-2011-doc...](http://blip.tv/pycon-us-
videos-2009-2010-2011/pycon-2011-documentation-driven-development-4896872)

------
1337p337
"The whole point of the Doomsday Device is lost if you keep it a secret. Why
didn't you tell the world?"

I can't be the only one to hear Dr. Strangelove's voice every time
documentation is missing, can I?

------
tibbon
I've been trying to get better about just helping to fix the documentation
when its bad- but that is dependent on me being able to figure it out in the
first place with broken/poor docs.

------
ubernostrum
Amusingly, I gave a talk with pretty much this exact title at DjangoCon last
year, and am submitting an updated version of it for PyCon next year :)

------
_lex
I agree - I often just give up and read the source to figure out how to use
advanced features.

------
kerv
I'm pretty sure that if there was a manual for the software or application you
are using, you wouldn't read it anyways. The software should be intuitive in
the first place.

