The Principled Documentation Manifesto • Hacker News Board

Re: The Principled Documentation Manifesto

#11

Post by emin_gun_sirer » Mon, Feb 11, 2013, 3:11 PM UTC

bcoates wrote: post #6

emin_gun_sirer wrote: post #2

I wrote this, to turn my frustrations about the state of NoSQL documentation into something positive. I didn't think it'd get HN'ed so quickly. I look forward to suggestions for new gospel.

Your claim that "Chances are, if you're reading this, you already are a disciple" turned out to be true for me. Good job. I think everyone knows good and bad documentation when they see it, but breaking it down into actionable rules like this is great. If I could add something, it would be that there are both local and global assumptions, and both need to be specified. There are rules like "this input array must be s…

Interesting. There are certainly different kinds of assumptions and invariants. I like the idea of separating them by local vs. global scope; the latter are underdocumented.

Much as I like, say, the javadoc format, it channels devs into "function by function" thinking and documentation, and global assumptions and global invariants, typically do not get treated adequately.

Re: The Principled Documentation Manifesto

#12

Post by cincinnatus » Mon, Feb 11, 2013, 3:32 PM UTC

emin_gun_sirer wrote: post #9

cincinnatus wrote: post #7

Earlier quoted context omitted.

A bit of time making this more concise and cleaning up the language would go a long way when you get the time. Clarity above all other virtues for documentation, goes doubly for meta-documentation.

Very true. I get wordy when I'm pressed for time. If you write a new, simpler, easier version (Gideon's?), I'll put one in every hotel room.

It is always as Twain said, "Sorry for the long letter, I didn't have time to write a short one."

The essential advice of all writing: the simplest word choice, the fewest words, is doubly true for technical documentation. Unfortunately only 1% of tech writers seem to follow it.

And as you say, there never seems to be enough time left to document. This is why: a) the doc should be the spec b) write the doc first.

There, that's the concise version of your manifesto :-)

Re: The Principled Documentation Manifesto

#13

Post by feralchimp » Mon, Feb 11, 2013, 3:56 PM UTC

If you're wondering how to write thorough doc for an engineering audience, I highly recommend looking at IBM's doc for z/OS. The first thing you'll notice is: there's a lot of it.