Documentation is King

http://kennethreitz.org/open-source-and-constraints.html

by kenneth_reitz • 14 years ago

85 19 14 years ago

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• 14 years ago

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.

Perceptes• 14 years ago

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?

buster• 14 years ago

I can feel your pain.. Maybe you can convince them to update atleast the docstrings and use some documentation generation tool? That's mostly only API docs but still... it's near the code that is touched and should be just on the screen while changing code :)

meaty• 14 years ago

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.

powatom• 14 years ago

Documentation should most certainly be updated as the code changes.

Programmers should realise that the documentation is just as important (if not more so) than the code itself. If people don't know how to use your wonderful API, then it's useless.

If your comments don't accurately reflect the current code, then either the comments are wrong, or your code is: it's dangerous to have outdated comments in the code - somebody may come along, read the comments, and 'correct' the code because the code didn't do what the comments described it as doing.

dexen• 14 years ago

A man with one watch knows what time it is. A man with two watches is never quite sure.

Documentation and code can, and surely will, diverge from one another, leading to all kinds of nasty misunderstanding. As long as there aren't any reasonable† tools for keeping them in sync, it's best to avoid the problem altogether.

IMHO it's good practice to have separate `implementation' (mostly code and static data) and `businesse requirements' (mostly documentation). Minimize overlap, strive for singular responsibility: it should be clear whether a particular change should go into documentation (change in requirements) or into implementation (to match the requirements).

Tangentially related, if you have a habit of using `git blame' (or equivalent in your SCM), commit comments are good place to mention changes in business requirements, especially small ones.

† nope, UML is not an aid here.

gbog2• 14 years ago

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• 14 years ago

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

andreasvc• 14 years ago

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.

taeric• 14 years ago

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.

3amOpsGuy• 14 years ago

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• 14 years ago

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

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.

ef4• 14 years ago

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.

saurabh2• 14 years ago

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

slowpoke• 14 years ago

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

saurabh2• 14 years ago

I am lazy.

swalsh• 14 years ago

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

Documentation is King

Related Stories