Making lasting documents doesn’t have to contradict agility, but conflicts occur. Of that I was reminded when switching
index.html of the technical User Guide of Adj (before starting work on Elasticdraw) from XHTML to HTML5, on a branch.
Traditionally building for endurance
For more than a decade I have preferred XML compliant documents, such as XHTML, because one
- can query one or many documents with XML tools (XSL, XPath, XQuery, XML databases) without need to serve documents from a specific server (which would have to be running), and
- can query content without documents having to be open inside a browser (which regularly change with version updates), for example as files on disk.
Documents being pure data means
- no custom code absolutely required, hence
- no dependency on custom code still being functional in the future.
Elasticdraw itself is being developed to enable long-term documentation of complex systems.
Trouble with perception
Long-term thinking, however, risks lack of appreciation when a disconnect from other thinking is perceived, such as: Save an aquifer, or have a great harvest this year? Use a proven standard, or look fashionable? Perception often starts with visual appearance.
Getting with the times
In implementing Elasticdraw, SVG inline in HTML5 has caused extra pain: Code complexity, effort to test and effort to iterate to ensure correctness. But, for perceivable modernity and agility, HTML5 is better than not having it.
Since supporting SVG inline in HTML5, now more contemporary looking documentation for Elasticdraw itself is a question of taking time.
Endurance still a criterion
That documentation nevertheless should be made faithful to principles of lasting usability by not getting too fancy, not too dependent on dynamic execution of code, and avoiding using not yet sufficiently established features of HTML5.
Comparable thinking has led to the PDF/A standard.
Some would suggest “just do it, don’t overthink it.” Anecdote has it, rapidly mass-produced suboptimal Sherman tanks helped win WW2.
Throwing out all other considerations to favor a small set of priorities isn’t right either. Supposed speed or supposed simplicity might merely be short-term or from a specific point of view.
My thinking about documentation is influenced by awareness of widespread and lasting system failures: Places where water flows from faucets only every other day, places where electrical outlets are powered only a few hours a day.
If your responsibilities include maintaining and rebuilding infrastructure, you may appreciate when your documentation system is resilient rather than finicky. Cannot fix your network after a cyberattack because you cannot get to the documentation server? Oh no.
If you have to recover from natural or man-made challenges, you don’t want documentation to be unavailable because the documentation system itself has too many dependencies.
Are you feeling better now, knowing folk designing Elasticdraw sometimes consider how to make a lasting solution?
Not just thinking: Features in Elasticdraw and surrounding tools already provide resilience, and have proven their effectiveness once at least, when one browser dropped part of a standard support. More about that another time.