Inconvenient truths and lessons learned

(in 40 years of documentation frustration)

First Lesson: Nobody reads the documentation! It‘s true, everyone praises the documentation, but almost no one reads it.

Second Lesson: XML is not self-documenting, or Why the Apple technique of no documentation does not work

There are many and varied reasons why semantic guessing might not work

To misquote Liam Quin only slightly: Documentation failures have been attributed to users assuming that they understood the content of an element when (perhaps) it had a misleading name.

Inconvenient Truth #3: — Creation, maintenance and governance are heavy loads. We all realize that it has to be somebody‘s responsibility to write and maintain documentation. But I have a day job, don‘t you?

Inconvenient Truth #4: — Documentation costs money

Did anybody budget for maintaining this?

When should documentation be performed? — The only wrong answer: After everyone who created the document grammar has gone

Inconvenient Truth #5: How do you measure quality? — or, to put it another way: What is good documentation?

There are some vague general rules that apply to documenting a tag set:

But that does not really answer the question. How do you measure good documentation? Good documentation may expose vocabulary flaws, but... the reverse does not hold. Programs can be tested, documentation not so much. Usability testing can help, with real users in real situations. So get your users involved!