
Documentation is King - kenneth_reitz
http://kennethreitz.org/open-source-and-constraints.html
======
3amOpsGuy
I've been doing some experiments to improve recall of documentation.

So far i've learned a few seemingly effective techniques:

1) Occasionally construct some weird sentences, throw grammar out the window
for a sentence (any longer doesn't work) and people will recall that whole
section of the document, months, even years later. I have no idea why this is
so effective, but i'd love to know.

2) State an assumption and have it missing the obvious consideration. Don't
make it some intricate detail, it has to be in plain sight even for someone
not familiar with the topic. Again, people recall these sections and are happy
to suggest how you could improve the document.

3) Never tell anyone you're playing tricks like this, it completely loses its
effectiveness when people know what you're doing with the slightly strange
documents.

4) Test the recall of others frequently on your text. Probe them and figure
out what's easy to remember and what's not. You can use this to tweak your
documents for future.

5) Don't over use it. The goal doesn't have to be to have them remember
everything, but it must allow them to remember where they found the
information previously.

YMMV, but i'm blown away so far and i haven't seen anyone talking about this
along similar lines yet. It all started after reading one too many psychology
books.

~~~
gojomo
You broke (3) with this comment!

Similarly, there's some research that less-legible text is recalled better:
[http://bps-research-digest.blogspot.com/2010/12/harder-to-re...](http://bps-
research-digest.blogspot.com/2010/12/harder-to-read-fonts-boost-student.html)

Compare also bloggers who intentionally oversimplify and make small errors in
their headlines/articles, guaranteeing more attention via outrage-forwarding,
a vibrant comment section, and 'hook' for a followup post that
extends/clarifies/apologizes.

Strightforwardness is good for many things... but not memorability.

------
Perceptes
I agree with this, but have had trouble getting support for the idea of
focusing on documentation among my coworkers. The major concern is that
comments can rot as code changes and the comments/documentation are not
updated to reflect the changes.

It's my opinion that it should just be part of the developer's discipline to
update documentation as they update code, but this seems not to be practical
when not everyone shares my idealism for documentation. What ways are there to
get buy in from those that need to be convinced about the value of
documentation?

~~~
meaty
Documentation is part of engineering. Hire engineers rather than two bit
coders. They already have the culture burned in.

Works for us. Most people not up to it I.e. find it boring or can't put a
sentence together bail in a month because they can't get their code through
the review cycle. They are made well aware of the requirements at interview
time.

We're in financial sector so sound engineering and documentation stops us
getting in deep shit.

Case in point recently, one of our service providers broke their service API
silently. We had their documentation, contracts etc set in stone in source
control, named and dated as were our integration paths. When they pointed the
finger at us, we were covered.

The small detail was recorded (1 penny rounding method) which meant we could
trace it instantly, pop open our log4j dumps and found that they sent the
value wrong. Not only that, we raised it to start with because our constraints
were documented and assertions were in place.

------
gbog
I always wondered if great tools like vim, nmap, git, etc. are successful
because they have great documentation, or have great docs because they are
successful.

maybe the answer is in the middle and above, great tool makers are great docs
writer.

~~~
swah
Its amazing how most manpages are better written than the average paper from
academia or product manuals.

~~~
andreasvc
Papers from academia present new results in a specialist area. It's not
surprising that they will be less readable and contain more jargon than a
manpage. The latter is intended to show how to use something for the general
computer user, not how it manages to do it. Furthermore manpages have the
chance to undergo many revisions, papers generally do not.

~~~
gbog
> It's not surprising

Being "not surprised" seem to be the new meme on HN. Anyway, let me disagree:
when you know how to write words in a sentence, you do it well under any
circumstances. (I forgot its name but there is a story of this British poet
whose one-sentence instruction sticker on how to handle the toilet flush was
such a precise and cristalline piece of prose)

So no, if academic papers are so poorly written now compared to manpages or
academic papers centuries ago, it is because academic people are worse
writers.

------
lifeisstillgood
I am becoming fascinated by finding better ways to document and communicate
about code - not just writing good docs as part of checkin but, well lets say
we take on a feature.

We should propose how to implement that feature, (spec) get some feedback, go
do it, review the implementation against the spec and even then I would want
to have a sort of stack overflow Q&A site so people can ask why did you do
that ?

Anyone else feel we are missing a whole boatload of tricks?

~~~
Hoff
When working on or editing documentation or the comments, I start with the
"two-year-old kid" review. I ask myself "why" and "what", and often
repeatedly, until I get to a concise answer.

What's this? Why is this here? Why do I want it? Why is this good? Why do I
care? Why? What's that mean? What's this knob do? What's that code do? Why is
this code here? Why?

Flabby documentation, user documentation written in programmer jargon and
scatter-shot code comments are all comparatively easy to write. When somebody
bothers to write that.

Writing for the end-user (whoever that might be) is tougher, and I find
require iterating on the content of the documentation, UI, release notes,
comments, or whatever. Writing less documentation or fewer comments — while
conveying the necessary details — is hard work.

------
taeric
Every time I face a rant like this at work, I need only fire up an editor and
pull up the source code to git. For loads of fun, load up date.c. There is no
disputing that git is high quality code that we rely on. My dispute is that
odd insistence on rigid documentation standards is silly in this context.

Note, this is not to say that documentation doesn't matter. It definitely has
a prominent role. So does "does the job." Preferably well. The blogger
mentions a prime lens works because it doesn't allow zoom. Sure it does, you
just have to move your feet. This can actually be rather annoying when you are
trying to get a candid shot in the house. Framing doesn't automatically happen
with a prime lens, that is. However, the quality of image from a prime is
huge. More than makes up for the short comings for many of us.

------
ef4
Producing great documentation requires the same kind of judgement as designing
the system in the first place: if you can consistently put yourself in the
mind of your reader, then your code, your APIs, and your documentation will
all be much better.

More documentation is not necessarily better. Just like code, the best
documentation is the documentation you never had to write because you found a
simpler way, and eliminated the issue completely.

------
saurabh
Hey Kenneth, I saw your tweet about wanting a .org for your website. Any
reason for the migration to a .org?

~~~
slowpoke
If you saw it on twitter, why don't you ask this on twitter?

~~~
saurabh
I am lazy.

------
swalsh
Its pretty old, but its hard to get better then Doxygen:
<http://www.stack.nl/~dimitri/doxygen/>

