(This Moose has spent an entire day (with a foul cold) trying to make head or tail of some product documentation that would be better off used for lighting fires.)

If I thought it would help the quality of documentation I usually have to deal with, I'd start a religion based on it and hand it out on street corners.

I'm afraid it's more aspirational than descriptive of the world I live in.

Hmm, I should print this out and take it to work, because I write a fair amount of documentation myself.

Amen! Hallelujah!

Praise The Lord!

...um. Maybe a couple additions:

7.) It is not long-winded; it useth not interminable constructions when simple words can fully express its ideas.

8.) It is well-edited and reads not like it was composed by committee.

9.) It is easily available in non-proprietary formats so I may print it on ordinary paper.

They'd be fools to in this case - it's 4 years out of date and describes nothing implemented in that time, and little or nothing of relevance to a current-day user. To him, that is apparently reason to never update it again.

Guide for developers to set up work environment
Build documentation
Install / configuration documentation
Patch build instructions
Patch install / removal instructions
Upgrade and downgrade instructions
Troubleshooting guide for technical support (e.g., how to find and read logs)
Guides for APIs
Guides for internal testing tools and utilities
Training guides and presentations

None of these, note, are user documentation.

Cadbury @ 2: It's good enough that it could light fires? I've had pieces for which I wanted to emulate Shaw: "I am in the smallest room in my house. Your doc is before me; shortly it will be behind me."
     OTOH both of those are at least uses; I'm told Data General's president once showed a supplier that his disk drive wasn't even usable as a boat anchor.

It had . . . many parts.

I was once tasked with bringing to contractors up to speed on it. I took advantage of a whiteboard in a vacant office. I filled all of it. After I turned it into a PowerPoint illustration a VP asked me if he could use it for a presentation.

I'm never going to work on that product again and I'm not sure if it ever saw the light of day, but I could reproduce that diagram from memory.

I love diagrams.

1: An Editor is not just the piece of software that lets you type words into it.

2: Not even BASIC is the same language as English.

3: JIRA is a tool to manage programmer's work. It is not a tool for users to report bugs.

4: Diagramming a sentence is orthogonal to determining what it means.

5: Human language is self-modifying code.

Any more?

(I'm an auditor, constantly attempting to thread the needle between "a well-documented disaster is STILL a disaster" [1] and "If it were broken, how would anyone be able to tell" [2].)

1) Credit to Megan McArdle
2) The correct answers include "because what it's supposed to do is written down"; unacceptable variants include "we haven't noticed any problem", "someone checked it when it was built--I think that was after 1990", and "it's APL--anyone who wants to can just look and see what it is doing".)

Those sound more like commandments....
10) Thou shall use screen shots where ever possible.

Which leads me to ask what are the hallmarks of really good documentation? 'Cause at my Day Job, I'm having to document business practices as they relate to assorted databases. (...and the business practices keep changing... I choose to be amused by the "This doesn't work so we're changing things" only to go back to the old way "Because the new method works less well than the old method." Lots of new administrators on board.)

It doesn't help that I have to keep explaining that Software A does not have anything at all to do with Software B or Software C, even though they use similiar data sets. Oh, and Softwares B and C kinda-sorta interface with each other, but not really even though they both do two sides of the same work.

"...sound like commandments."

Maybe a little. I could probably do a little more work to make them match abi's style, but today is a Honey-Do day, so I'm not going to expend the effort.

I like yours, by the way, though it also sounds like a commandment. Maybe "It useth screenshots, that I am not mislead."

Is it a sign of something bad that I now want to see a software-documentation version of Revelations?

No.

Why, oh, why do so few IT professionals really, truly understand the real, actual *need* for documentation!? Every time I take over a new network, I have to start from scratch and build the documentation up from nothing. And I always, always, *always* try my absolute best to leave my replacement enough documentation so that they can survive their first week without me. A luxury I have never, ever been afforded in my entire professional life.

CHip @15:
I don't know if it would help, but in point of fact Psalm 23 is one of the core texts for my own religious life. That's why I knew it well enough to pastiche it on a deep structural level.

Though not all Xians react the same way...

JK Hoffman @30:
Yes, go ahead and use it (blanket permission, folks, preferably with attribution).

-----
* She was J Paul Getty's secretary and an avid collector of 1940's office doggerel and jokes. I never met her—she died the year before I was born—but I suspect we'd have common ground in this area.

A really first-rate textbook is a work of art.

It's a good job he doesn't work for Competitor Acquisitions[1], with their penchant for OCO[2), then.

Cadbury (still with Foul Cold). <grump>

[1] More recognisable by their initials.
[2] Object Code Only.

1) Credit to Megan McArdle
2) The correct answers include "because what it's supposed to do is written down"; unacceptable variants include "we haven't noticed any problem", "someone checked it when it was built--I think that was after 1990", and "it's APL--anyone who wants to can just look and see what it is doing".)

Oh man ... I am -so- going to point our compliance folks at that ...

A good COBOL paragraph name was a good place marker to help you find WHAT you were looking for. (Yes, even COBOL wanted comments.

In any language, it's helpful to document WHY the code is doing that particular thing. Yes, any fool can see what is happening, but the why explanation can help reassure you that it still needs to happen. Or not.

I have not read
the FAQ
that was on
the webpage

and which
you were probably
hoping
I would read

Forgive me
I am impatient
and dumb
and lazy

I *have* read
the FAQ
that was on
the webpage

and which
you were probably
hoping
would answer my question.

Forgive me,
it did not.
FAQs seldom do.

*Heaven help you, because they won't.

The visual I remember was a bridge, with a sign saying "This is Bridge".

Does anyone know what it was/where i could find it?

Wiki pages that are nothing but oddly indented bulleted lists.

Bullet points in lieu of paragraphs, section headings, and etcetera.

Ran into one the other day that was a bulleted list entirely formatted as Heading 3.

I don't have that cartoon (though I'd like to) but it reminds me of a joke between my husband and me that dates back more than 30 years. I think it was one of his classmates or early coworkers and not one of mine whose had inserted a comment in a program saying "This section iterates."

Well, yeah. That's an examplar of "true but not helpful."

Also, once upon a time long ago, some coworkers and I were asked to create some problems/questions for a programming class. There were the usual things like a loop that was one-off in counting whatever it was supposed to count, but my fiendish favorite was a short piece of code that included a snippet that didn't quite do what the comment said it did.

Both of those are very true, but I usually fall into 45 rather than 44.

SamChevre @ 52:

It appears to be an Abstruse Goose cartoon, and I'm not sure whether I found it funny or all too true.

Yes, that's it. THANK YOU!

Win! (as it were)