
The Principled Documentation Manifesto - aydinhan
http://hackingdistributed.com/2013/02/11/principled-documentation/
======
emin_gun_sirer
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.

~~~
jacques_chester
I find the "commandments" format to irk me slightly. I realise it lends a
ready-made structure to any document, but "thou shalt" is sufficiently fusty
that it can rub people the wrong way.

I've found the pattern format to work well in practice, because a well-written
pattern pretty much explains itself. In particular, framing the discussion
with a problem helps to illuminate when and where a pattern ought to be
applied.

In terms of your general thesis in #2-5 that formal specification has failed
and that a structured form of informal specification (wrap your head around
that one, fellow pedants) ... I'm not sure.

I mean some of what you've argued for seems to me to be a "language design
smell" -- just as some of the original Go4 patterns were seen in retrospect to
be. So for example when you argue for taking a contractual approach. Why
shouldn't that be in the language? It's not as though you have to go all the
way to writing Z specs or Coq proofs. Personally I'd be perfectly happy to
step up to Eiffel contracts.

Guarantees embedded in source code also have the nice property that they are
slighly less likely to turn out to be filthy horrid lies; just as is generally
thought of sourcecode comments.

I agreed with point 7, about stating the end state of the method rather than
its process. I feel the same way about tests; I find test doubles to be
thoroughly unsettling because I wind up explaining the logic of my program
twice, instead of separating mechanism and validation. Perhaps such "naked
mechanism" is just another indicator of code that will require high coupling.

Where you went wrong was that you, like I, assume that things with "database"
on the label have silly-old fashioned notions like a fanatical focus on data
safety.

I also agreed strongly with 8 and 9. Sometimes I look at the front page of HN
and it is totally unintelligible gibberish. Having to know the intricate
injokey history of two dozen sequential puns to run a piece of software drives
me up the flaming wall. It's one of the things I least like about the ruby
ecosystem.

~~~
cabalamat
> "thou shalt" is sufficiently fusty that it can rub people the wrong way

Particularly when used inconsistently, e.g.: Thou shalt specify _your_
assumptions

------
mr_luc
Treating docs like specifications may seem onerous because of the specs that
come to mind: entire languages, or the CSS/HTML specs. Massive documents, way
too much work.

But I fell in love with the CL HyperSpec years ago. Pick any section,
(<http://www.lispworks.com/documentation/HyperSpec/Front/>) ... and it's
amazingly clear, with sample code and everything.

And, yeah, it's a big spec. But CL is a big language, and not just any
language, but a batteries-mostly-included language, fully specified.

In contrast, the programmer-facing API for most libraries is going to be
fairly small. HyperSpec-quality docs probably wouldn't be that hard for most
small-to-midsized projects.

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

