Quotulatiousness

November 18, 2015

ESR on “Hieratic documentation”

Filed under: Technology — Tags: , , — Nicholas @ 02:00

Eric S. Raymond explains how technical documentation can manage the difficult task of being both demonstrably complete and technically correct and yet totally fail to meet the needs of the real audience:

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.

No Comments

No comments yet.

RSS feed for comments on this post.

Sorry, the comment form is closed at this time.

Powered by WordPress