That's lovely abi!

Simply Superb!

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

::applause::

Hear hear! This right here is a thing of beauty.

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.

That's great.

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.

Good documentation is indeed a boon. Just today there was an item in my local paper from someone who had purchased a solar charger and found this as the last sentence of the instructions:
“We reserve all the rights for the final explanation.”

This is going up in my cube at work, and will also be posted on the company Slack. With appropriate attribution, of course, because I am married to an academic.

That's splendid, Abi. Brava!

abi, you are speaking in tongues and handling snakes and I can feel the power of the Lord Our Documenter in your words, so I'm just gonna sit back and hum while you preach it.

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.

Allan Beatty@5: That's quite precisely what I was thinking myself.

I'd like to post that at work, but I'm not sure some folks would take that wrong.
* * *
I joined (um, was thrust into) a new product group last fall. There is a LOT of not-written-down information. I've spent my slack time updating Wiki entries and writing new ones. Command line usage for utilities, procedures with examples for using them, test procedures.

Well, not 10 minutes ago I just pressed (again) for us to put some effort into bringing our manual up to date - after my boss bitched at me about how he doesn't think any customers are using one of the new features he implemented last year - and got the answer "Well I don't think anybody would read the manual anyway."

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.

That's wonderful! I think I'll print it up for work.

On my last project (I'm a QA folk) I drew up a list of documentation required. The developers were a research group that hadn't, for the most part, ever delivered a product for actual deployment before:

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.

I love this. But if I were still working I'd be stuck wondering which kind of mistake sending it to the doc group would be, as statistically they might include one Xian.

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.

I wish I were at liberty to post diagrams of my previous project assignment.

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.

Documentation and Programmers List

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?

Sadly, many companies now believe that because their documentation is being delivered online and therefore it can be changed and updated more frequently, there is no need to polish it, and therefore no need for technical editors. I wish this were not the case not only because the quality of product documentation is suffering but also because I suddenly lost my technical editing job of 24 years recently and there aren't very many positions out there...

Emailed to the software group at work, who are notoriously bad at updating the specs :(

"Why don't you just make a video using your phone and upload it to YouTube?" asked the marketing dude who sells the server-side software but only ever reads self-help/business books.

Oyez! Oyez! Oyez!

(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".)

#20: I've gotten instructions in video form -- captured animated screen shots really -- from developers in other sites on how to perform certain operations. I find this infuriating.

Alex R @ #9

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.

@ Victoria

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

Formatted up for cube-posting:
The Good Documentation

Jude @ 25 -- Thank you!

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

Jordin @ 27

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

No.

Jordin, Alex R: Well, I'd say it is a sign of something bad -- just not bad in Jordin! It's a sign of the state of our Documentation Apocalypse.

I'll be using this in meetings with my fellow sysadmins. (Assuming that's okay with you, Abi. Is it? Attributions will be included, of course!)

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.

I'm glad to have contributed to office culture! Thank you, Jude @25

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.

Good documentation deserves more praise than it usually gets. One of the most useful books I ever read was the (free) Linux manual Rute User's Tutorial and Exposition by Paul Sheer. Beautifully clear explanation of how Linux works under the hood, and full coverage of all the command-line tools. I read it from cover to cover over a weekend. It's probably a bit outdated now but at the time, it was precisely what I needed.

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

Applause and laughter in equal measure. Thank you, abi.

Dave Bell at # 17: At my workplace, Jira is a tool for arguing whether something is a bug or a new feature request.

I've been working for years with a developer who will loudly, pugnaciously tell you at any opportunity that documentation is a bad thing because it can get out of date and then it'll be wrong and that's worse than never having any. In his opinion, anyone who really wants to know something about the software should just read the source code. (That is, the code proper-- not the comments in the code, since by the same principle, there shouldn't be any. And yes, this is one of those people, very familiar to anyone who's dabbled in functional-style programming, who insists that you shouldn't care about having understandable names for anything in your code, because the data types are all that matter.)

Hob @ #35

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.

SamChevre @ 21 ...
(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".)

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

It's been a while since I wrote--or documented--any code, but I do remember a couple of principles that stood me in good stead:

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.

Hob@35:Yes, I know that person[type].

@39: Well, I guess he would tell you that if you know the type, there's nothing else you need to know about the person...

(That's not my own philosophy for dealing with people, just a joke about data types)

Is there one of these for testing? I need to pass it around in my company. Don't get me wrong, there are plenty of people who know how to test—they just think it's okay to start testing after deployment.

Hob@40&41: :-)

This Is Just To Say

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

This Is Just To Say

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.

Mary Aileen, #45: NO SHIT. Also, when you can't find the answer to your question on the website and you've gotten desperate enough to call, the phone menu only provides the SAME information that's on the website, and takes 7 minutes to get to an option that will let you reach an actual human being who might be able to address your problem.

Lee (46): And, if you're calling Verizon*, the on-hold message suggests trying their website. Excuse me, if your website had the information I wouldn't be wasting my time on hold! (Not that I'm still bitter, or anything.)

*Heaven help you, because they won't.

44 v 45: the eternal schism between developers and users will never be bridged.

cleek (48): Truer words were never spoken.

Also, "Emailing the devs (at, say, bugs@companyname.com) is NOT a bug-reporting interface."

Mary Aileen @ 47: I think that's in the same category as "please listen to the options as our menus have changed" (years ago); it might save them a tiny slice of people time (through making people who don't think to look do so, or not having to forward a misdirected call) and the sound bits cost nothing, so it's reasonable to do -- never mind how much it annoys the 99+%.

There was an excellent cartoon on documentation (the useless sort), which I had on my cube wall and lost in a move. I think it was xkcd, but have looked for it multiple times.

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?

Well-intentioned documentation habit that drives me bugfuck:

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.

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

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.

Mary Aileen @ 44/45:

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.

KeithS @ 55

Yes, that's it. THANK YOU!

KeithS, #55: Both, perhaps?

Thank you thank you Abi! I love it. On top of it being hilarious, I found it at just the right time. Tonight I have a technical speech which was a bit short and needed a hook. But now I have this fabulous quote to patch into the opening...

Wyn @58:

Win! (as it were)