Hieratic documentation

Here’s where I attempt to revive and popularize a fine old word in a new context.

hieratic, adj. Of or concerning priests; priestly. Often used of the ancient Egyptian writing system of abridged hieroglyphics used by priests.

Earlier today I was criticizing the waf build system in email. I wanted to say that its documentation exhibits a common flaw, which is that it reads not much like an explanation but as a memory aid for people who are already initiates of its inner mysteries. But this was not the main thrust of my argument; I wanted to observe it as an aside.

Here’s what I ended up writing:

waf notation itself relies on a lot of aspect-like side effects and spooky action at a distance. It has much poorer locality and compactness than plain Makefiles or SCons recipes. This is actually waf’s worst downside, other perhaps than the rather hieratic documentation.

I was using “hieratic” in a sense like this:

hieratic, adj. Of computer documentation, impenetrable because the author never sees outside his own intimate knowledge of the subject and is therefore unable to identify or meet the expository needs of newcomers. It might as well be written in hieroglyphics.

Hieratic documentation can be all of complete, correct, and nearly useless at the same time. I think we need this word to distinguish subtle disasters like the waf book – or most of the NTP documentation before I got at it – from the more obvious disasters of documentation that is incorrect, incomplete, or poorly written simply considered as expository prose.

28 comments

    1. >Would you consider most of Git documentation hieratic?

      The manual pages often are, though the picture is mixed and the situation seems to be gradually improving.

  1. I have to agree with you on the state of the waf book; over the past week or so I have read the whole thing trying to figure out how to integrate autorevision into a generic waf build and have been unable to do so.
    Not only have I gotten the impression that the information is presented in a way that makes assumptions about the reader having some previous knowledge of how waf works but I also feel that there are not enough examples and those examples that exist are not well enough annotated to make them easy to decipher.

    Comparing it to git documentation (man pages) depends on what version of git one uses as a reference: I would say that the current (2.6.2) version version is ok though earlier versions were much worse, though I think even when I first started using git heavily (1.6 or so) it was better than where the waf book is today.

  2. The general distinction is, of course, usually between a reference manual (which this sounds like) and a User Guide or (even more detailed) a Tutorial.

    It’s not at all uncommon for things which are developer focused only to have the first, if they have anything at all other than a man page and a –help screen; another word for the thing you’re looking for is nerdview, though there’s no adjectival form.

    1. >It’s not at all uncommon for things which are developer focused only to have the first, if they have anything at all other than a man page and a –help screen

      Right. A problem arises when maintainers like Nagy issue something like the waf book which claims to be a tutorial and crowds out the production of a tutorial, but is too hieratic to actually be a tutorial.

  3. > hieratic, adj. Of computer documentation, impenetrable because the author
    > never sees outside his own intimate knowledge of the subject ….

    THIS!

    Another example I’ve found is the Roundup design doc. I’ve tried at least three times to wrap my head around the its over-all structure, and I seem to always stumble over some implicit or hidden assumptions the authors have made.

    (I’m strongly tempted to dig into the sources far enough to write my own intro. o_0)

  4. “hieratic, adj. Of or concerning priests; priestly. Often used of the ancient Egyptian writing system of abridged hieroglyphics used by priests.”

    I came to that conclusion back in the 80’s, learning AT&T System V and reading man pages. They were references, not tutorials, and implicitly assumed you knew various things, or had a guru on site to impart the knowledge. (If you *were* the guru on site, and the man page wasn’t clear, fun ensued.)

    It made sense in the setting in which Unix arose, since the folks developing Unix and writing and reading man pages were mostly at the Murray Hill facility and could simply talk to each other. As development becomes geographically distributed, that model falls down fast, but lots of open source projects don’t seem to have learned that. I’m tempted to propose a drinking game where you take a shot for every project you see that doesn’t include an obvious tutorial, and two shots for every one where you have to dig to simply find out just what the software is supposed to do.

    We would all be under the table in short order.
    ______
    Dennis

  5. When I’m writing documentation (for our extension APIs to our product at work), I always go over it, following exactly the steps and requirements I wrote down in the docs, and make sure that produces a working extension.

    If not, I add whatever I had to do that wasn’t documented … to the documentation.

  6. > I know. I was that guy. :-)

    Speaking of you in the old days, I’ve been reading various newsgroups from 1985 on olduse.net, and I’ve seen a lot of notable-ish names pop up, but not yours (none from here, in fact). Just out of curiosity, were you on Usenet in 1985?

  7. hieratic, adj. Of computer documentation, impenetrable because the author never sees outside his own intimate knowledge of the subject and is therefore unable to identify or meet the expository needs of newcomers. It might as well be written in hieroglyphics.

    Etiquette question: Eric is a high-status hacker. When he complains about hieratic documentation, High Priests feel a reputational incentive to fix it. But if a muggle studies a program’s documentation and finds it hieratic, it frequently doesn’t work. What is the proper protocol for explaining the problem to the high-priestly documenter?

    I’m sure that a large part of the answer is to follow at least the spirit of Eric’s article on how to ask smart questions. But when it comes to documentation, there seems to be something different going on in addition. I’ve seen numerous dead-end threads on mailing lists where laypeople did ask smart questions about the documentation and the high priests seemed to mistake being uninitiated for being stupid. A typical if stylized exchange goes like this:

    Layperson: “After studying chapter 5 of the Foo tutorial, “How to do a Bar in Foo”, I’m still unclear on how to do a Bar. The problem seems to be that the tutorial is written from an implementer’s point of view, not a new user’s point of view.

    High Priest: “Fine, send me a patch and I’ll apply it.”

    Layperson: “I can’t send you a patch because I don’t know Foo yet. That’s why I’m reading the tutorial, see, to learn Foo programming.”

    (alternative conversation:)
    High Priest: “Can’t use the documentation? Then Use The Source, Luke (TM)!”

    Layperson: “I don’t understand the source. I could really use a readable, user-friendly guide to find my way around in it.”

    Either way, it all goes downhill from there. Hence my question: Under the customs of hackerdom, how does a nonhacker layperson say, “high priests, your documentation is hieratic”, and say it in such a way as to have a fighting chance of improvement rather than mutual frustration?

  8. Either way, it all goes downhill from there. Hence my question: Under the customs of hackerdom, how does a nonhacker layperson say, “high priests, your documentation is hieratic”, and say it in such a way as to have a fighting chance of improvement rather than mutual frustration?

    The way I do it is 1) top level problem statement,
    2) specific points where there are issues and
    3) what I have tried as a result of reading 2) and getting confused with the output/ error messages etc. seen.

    I.e. I start with something like
    After studying chapter 5 of the Foo tutorial, “How to do a Bar in Foo”, I’m still unclear on how to do a Bar. I’ve been struggling with Chapters 1-4 too but the lack of clarity in Ch5 was far worse. Unfortunately I really need to do a Bar using Foo so I’m asking for some help

    Then get into details
    I managed to do baz in section 5.1.
    (output)
    however it was unclear what I was supposed to do next. section 5.2 (the baz-boo converter)
    I tried using foo –barbaz bar and got the following error
    (error invalid baz, out of cheese error redo from start)
    and have no idea how I add cheese to my baz
    It looks like I could also go direct to doing bar (using the –magic-incantation option in section 5.3) however when I try
    foo –magic-incantation=abracadabara >bar
    I get the error
    (error failed to initialize GBL)

    Do I need to add –sacrificial-victim option (5.4) and if so what should it be? I tried goat, virgin, priest and cheese? The –widdershins flag also made no difference to the results

    Finally there’s a section on environment and an offer to help by providing usecases that work
    I’m running the latest foo (v.3.14) on a Discworld Hex V1.5.1 build 12345 with 2.5 ramtops and a floppy hat. I attach all the options tried and the output. it attachment.txt

    I’ll be happy to contribute my workflow back to the foo project to be added as a HOWTO or tutorial once I have successfully done bar

    Best regards
    R Wind

    Generally speaking I get moderately helpful responses “you forgot to specify –candles=black –candle-count=5 see chapter 9 or P Stibbons wrote a tutorial at blahblahblah that covers this” and in the cases where I haven’t it’s generally a sign that either the project is now dead or that the developers don’t care and in either case it typically means I should choose a different tool to solve my problem.

    1. >I’m running the latest foo (v.3.14) on a Discworld Hex V1.5.1 build 12345 with 2.5 ramtops and a floppy hat. […] you forgot to specify –candles=black –candle-count=5 see chapter 9 or P Stibbons wrote a tutorial

      Francis T wins the thread. I totally laughed my ass off reading this.

    1. >I wonder if “solipsistic documentation” (the programmer is forgetting that other minds exist) would be clearer than “hieratic documentation”.

      That’s really good!

  9. Some years back I heard of a tech company which only hired tech writers on short-term contracts. (Well, middle-term – six months to a year.) The job of the writers was to explain the company’s products to novice users. But after six months to a year, a writer would know the product too well, and his writing would come to assume knowledge the reader wouldn’t have.

    So the tech writing staff had to be turned over about once a year.

  10. I needed a word for this last week. Without naming names, I was looking at a tech note about $APPLICATION that explained how to edit a config file, which then said to bounce the application and I should see certain things in the XYZ log. The application in question runs as three daemons, and “bounce” did not specify which of the daemons needed to be restarted, nor was “XYZ” part of the filename of the actual log file, but is an initialism for a name under which that log was described years ago.

    I was talking to one of the app’s vendor support people about a separate issue and brought up this tech note. I found out the info I needed (actual filename of the log file, and all three daemons must be restarted for the changes to fully take effect) and asked him to relay to the people who maintain these tech notes that it the whole reason we need to read their work is because we don’t know what they know, and assuming we do isn’t helpful.

  11. Most linux application documentation jumps from intelligence-insultingly simplistic to hieratic in one swell foop somewhere after the introduction. (Maybe it’s not that bad, I’ve been a unix novice for a *long* time, so it’s possible that stuff I find insultingly simple really is useful to newcomers.)

    Most of it is not wrong, per se, but examples are given with nearly no clue how to do something slightly different than the example. The man page for find is like that – small changes in the line-noise portion of the expression makes a big difference, but those aren’t explained well, if at all, and doing anything new with find requires lots of trial and error. The documentation for ImageMagick and GraphicsMagick are worse, in a somewhat different way – there are a lot of options to do lots of very powerful things, and there’s a relatively clear explanation of what each option does, but the documentation is too poorly organized to explain the basic concept of how to construct useful command lines without a lot of digging, and there are some significant gaps in explaining some of the more powerful features.

  12. “Passive aggressive documentation”.

    It won’t help you understand, but you will be referred to a sub-paragraph of it.

  13. I just came across this, by the way.

    It … well, at a glance I can’t tell it apart from a real git manpage.

  14. How would you suggest one write “demotic” documentation?

    My approach is to document before I code. What do I document? The whole design process, from the initial motivation, through all the design decisions, the reasons for the tools I chose, to every object and operator, how I want these to interact and why, and all problems and solutions as they occur. Ideally, the result is vibrant documentation that constitutes a forward-looking tutorial on every aspect of this project, written with love as I create it.

  15. > How would you suggest one write “demotic” documentation?
    >
    > My approach is to document before I code […]

    The problem is then with keeping documentation up to date. Because as you are coding, as you are writing prototypes and getting user feedback, programs change. Documentation should change with them, emphasiis on should…

  16. …but nevertheless, you will need such documentation for the API itself. The API documentation is a contract; given these inputs, this is what the output will be. Such that: if the documentation and the code disagree, the documentation is correct.

    Internal documentation may be hit or miss, of course. Miss for the obvious reasons. Hit, for perhaps less obvious reasons: sometimes the innards are complex enough that internal docs give you or some other dev helpful reminders of what $HairyBlock is supposed to do, whether or not it actually does it.

  17. Jakub, your point is well taken. Certainly what I practise is much easier to achieve in individual projects than in team efforts where contributors may have quite divergent habits. It took me many years to realise that neglecting to document and rushing to code was a miserable way to program.

Leave a Reply to Jakub Narebski Cancel reply

Your email address will not be published. Required fields are marked *