Back to previous post: On sale today: Charlie Jane Anders’ debut science fiction and fantasy novel, All the Birds in the Sky

Go to Making Light's front page.

Forward to next post: Gentleman Jole and the SPOILER Queen

Subscribe (via RSS) to this post's comment thread. (What does this mean? Here's a quick introduction.)

January 27, 2016

The Good Documentation
Posted by Abi Sutherland at 04:56 PM * 59 comments

It knows its systems and its systems know it.

I’ve spent the last two days in all-day work meetings, for Reasons. And although it’s not my main thing any more, I got rather emphatic—more than once—about the need for good documentation. It became kind of a Thing. It may haunt me in the future.

And then I come home to this in my Twitter feed:

Really, what’s a pastiche-monger to do?

Well.

1The DOCUMENTATION is my guide; I shall not wonder.
2It maketh me to understand the necessary concepts;
It leadeth me through the installation process.
3It reassureth me;
It leadeth me on the happy path for my desired objectives.
4Yea, though I work through the advanced configuration menus,
I will fear no failures, for thou art with me
Thy FAQ and thy troubleshooting they comfort me.
5Thou providest examples to me in the context of mine use cases.
Thou explainest my expected outcomes.
My results are perfect.
6Surely good performance and stability will persist throughout the system life
And it will run within the parameters of the DOCUMENTATION forever.
Comments on The Good Documentation:
#1 ::: Soon Lee ::: (view all by) ::: January 27, 2016, 05:36 PM:

That's lovely abi!

#2 ::: Cadbury Moose ::: (view all by) ::: January 27, 2016, 05:38 PM:

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

#4 ::: KeithS ::: (view all by) ::: January 27, 2016, 05:52 PM:

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.

#5 ::: Allan Beatty ::: (view all by) ::: January 27, 2016, 07:03 PM:

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.

#6 ::: Mary Jean ::: (view all by) ::: January 27, 2016, 07:10 PM:

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

#7 ::: Jude ::: (view all by) ::: January 27, 2016, 07:33 PM:

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.

#8 ::: Edmund Schweppe ::: (view all by) ::: January 27, 2016, 07:43 PM:

That's splendid, Abi. Brava!

#9 ::: Alex R. ::: (view all by) ::: January 27, 2016, 08:22 PM:

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.

#10 ::: David Goldfarb ::: (view all by) ::: January 27, 2016, 08:59 PM:

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

#11 ::: Stefan Jones ::: (view all by) ::: January 27, 2016, 09:16 PM:

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.

#12 ::: Clifton ::: (view all by) ::: January 27, 2016, 09:53 PM:

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.

#13 ::: BravoLimaPoppa ::: (view all by) ::: January 27, 2016, 10:02 PM:

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

#14 ::: Stefan Jones ::: (view all by) ::: January 27, 2016, 10:29 PM:

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.

#15 ::: CHip ::: (view all by) ::: January 27, 2016, 10:51 PM:

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.

#16 ::: Stefan Jones ::: (view all by) ::: January 28, 2016, 01:09 AM:

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.

#17 ::: Dave Bell ::: (view all by) ::: January 28, 2016, 01:51 AM:

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?

#18 ::: smofbabe ::: (view all by) ::: January 28, 2016, 04:02 AM:

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

#19 ::: Dave Crisp ::: (view all by) ::: January 28, 2016, 04:11 AM:

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

#20 ::: Charlie Stross ::: (view all by) ::: January 28, 2016, 08:50 AM:

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

#21 ::: SamChevre ::: (view all by) ::: January 28, 2016, 09:24 AM:

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

#22 ::: Stefan Jones ::: (view all by) ::: January 28, 2016, 09:48 AM:

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

#23 ::: Victoria ::: (view all by) ::: January 28, 2016, 09:48 AM:

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.

#24 ::: Alex R. ::: (view all by) ::: January 28, 2016, 11:11 AM:

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

#25 ::: Jude ::: (view all by) ::: January 28, 2016, 11:29 AM:

Formatted up for cube-posting:
The Good Documentation

#26 ::: Incoherent ::: (view all by) ::: January 28, 2016, 11:36 AM:

Jude @ 25 -- Thank you!

#27 ::: Jordin ::: (view all by) ::: January 28, 2016, 12:00 PM:

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

#28 ::: Alex R. ::: (view all by) ::: January 28, 2016, 12:44 PM:

Jordin @ 27

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

No.

#29 ::: Tom Whitmore ::: (view all by) ::: January 28, 2016, 12:52 PM:

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.

#30 ::: J K Hoffman ::: (view all by) ::: January 28, 2016, 01:02 PM:

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.

#31 ::: abi ::: (view all by) ::: January 28, 2016, 01:51 PM:

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.

#32 ::: Steve with a book ::: (view all by) ::: January 28, 2016, 02:37 PM:

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.

#33 ::: Lin Daniel ::: (view all by) ::: January 28, 2016, 05:50 PM:

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

#34 ::: Allan Beatty ::: (view all by) ::: January 28, 2016, 07:20 PM:

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

#35 ::: Hob ::: (view all by) ::: January 29, 2016, 12:42 PM:

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

#36 ::: Cadbury Moose ::: (view all by) ::: January 29, 2016, 05:17 PM:

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.

#37 ::: xeger ::: (view all by) ::: January 29, 2016, 09:29 PM:

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

#38 ::: Barry Newton ::: (view all by) ::: January 31, 2016, 01:50 PM:

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.

#39 ::: Steve Halter ::: (view all by) ::: January 31, 2016, 11:42 PM:

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

#40 ::: Hob ::: (view all by) ::: February 01, 2016, 07:55 PM:

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

#41 ::: Hob ::: (view all by) ::: February 01, 2016, 07:56 PM:

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

#42 ::: Allan Beatty ::: (view all by) ::: February 03, 2016, 07:14 PM:

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.

#43 ::: Steve Halter ::: (view all by) ::: February 03, 2016, 09:48 PM:

Hob@40&41: :-)

#44 ::: cleek ::: (view all by) ::: February 04, 2016, 03:57 PM:

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

#45 ::: Mary Aileen ::: (view all by) ::: February 04, 2016, 04:07 PM:

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.

#46 ::: Lee ::: (view all by) ::: February 04, 2016, 04:32 PM:

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.

#47 ::: Mary Aileen ::: (view all by) ::: February 04, 2016, 04:57 PM:

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.

#48 ::: cleek ::: (view all by) ::: February 04, 2016, 06:03 PM:

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

#49 ::: Mary Aileen ::: (view all by) ::: February 04, 2016, 06:48 PM:

cleek (48): Truer words were never spoken.

#50 ::: Elliott Mason ::: (view all by) ::: February 04, 2016, 07:26 PM:

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

#51 ::: CHip ::: (view all by) ::: February 04, 2016, 07:52 PM:

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

#52 ::: SamChevre ::: (view all by) ::: February 05, 2016, 08:44 AM:

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?

#53 ::: Stefan Jones ::: (view all by) ::: February 05, 2016, 10:04 AM:

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.

#54 ::: OtterB ::: (view all by) ::: February 05, 2016, 10:36 AM:

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.

#55 ::: KeithS ::: (view all by) ::: February 05, 2016, 01:32 PM:

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.

#56 ::: SamChevre ::: (view all by) ::: February 05, 2016, 02:48 PM:

KeithS @ 55

Yes, that's it. THANK YOU!

#57 ::: Lee ::: (view all by) ::: February 05, 2016, 06:58 PM:

KeithS, #55: Both, perhaps?

#58 ::: Wyn ::: (view all by) ::: February 18, 2016, 04:05 PM:

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

#59 ::: abi ::: (view all by) ::: February 18, 2016, 04:07 PM:

Wyn @58:

Win! (as it were)

Welcome to Making Light's comment section. The moderators are Avram Grumer, Teresa & Patrick Nielsen Hayden, and Abi Sutherland. Abi is the moderator most frequently onsite. She's also the kindest. Teresa is the theoretician. Are you feeling lucky?

Comments containing more than seven URLs will be held for approval. If you want to comment on a thread that's been closed, please post to the most recent "Open Thread" discussion.

You can subscribe (via RSS) to this particular comment thread. (If this option is baffling, here's a quick introduction.)

Post a comment.
(Real e-mail addresses and URLs only, please.)

HTML Tags:
<strong>Strong</strong> = Strong
<em>Emphasized</em> = Emphasized
<a href="http://www.url.com">Linked text</a> = Linked text

Spelling reference:
Tolkien. Minuscule. Gandhi. Millennium. Delany. Embarrassment. Publishers Weekly. Occurrence. Asimov. Weird. Connoisseur. Accommodate. Hierarchy. Deity. Etiquette. Pharaoh. Teresa. Its. Macdonald. Nielsen Hayden. It's. Fluorosphere. Barack. More here.















(You must preview before posting.)

Dire legal notice
Making Light copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 by Patrick & Teresa Nielsen Hayden. All rights reserved.