Home (contents) → Miscellaneous → Technical Writing and Programming → Document maintainability
Document maintainability
Disclaimer: The views expressed on this page are mine and do not necessarily accord with those of any of my employers, past or present.
The great advantage of web pages such as this one, and of all documents with hypertext links, is that the reader can traverse those links to related topics simply by clicking. When you have viewed the related (target) topic, you click your browser’s Back button to resume from where you were. That is much easier than the equivalent in a printed document, which typically refers you to a page number, and hopefully you don’t lose your place where you were… Unfortunately, a disadvantage of hypertext technology is link rot, primarily broken links, and secondarily mismatch between link text and the title of the target topic. (The two should be identical.)
However, until technical authors and the tools available to them become more capable, there will continue to be a trade-off between readability and maintainability of documents, web sites, online help, and similar. While ‘single source’ documentation is the ideal, implementing it is notoriously difficult. Nonetheless, even going part way to that goal garners rewards in a more rational compromise between readability and maintainability.
| Single source: You amend some text or a graphic image, click Update, and every link and reference to it throughout the world is automatically updated, database-style. In addition, language translations are automatically re-translated and human proof-readers of those translations are alerted. |
Broken links typically result from moving a page in the structure of your document or web site, which might entail moving it in a folder (directory) hierarchy or moving it in what programmers recognize as a ‘linked list’, or moving material from one page to another. Wording mismatch between the link text and the title or subtitle to which it links, which is less serious, results from rewording the title or subtitle. In both cases, you must amend each link to the affected topic. (Technically speaking, a hyperlink takes you to an anchor, which should never be anywhere but a title or sub-title.) There might be many, many links to an anchor. I am sure that there are sophisticated ‘authoring’ programs available that help with this kind of task, but I have yet to encounter one that completely automates such corrections. (The help editor at my last workplace could find every link to an anchor, which assisted hugely.)
Importantly, changes in structure and wording that cause link rot must always be allowed because the author or programmer gains insight by reading what he wrote — or by trying out the program he has coded — and changing it accordingly. And in the age of ‘agile’ development, end users or their representatives also provide such insights. Time-pressed managers hate to hear this, but value to the end user is only really added in that necessarily time-consuming and ‘manual’ reworking of the document, web site, or program. Before that reworking, software is often for show, not go, regardless of its creator’s intent. For an extreme example, see The importance of proofreading.
Damage limitation
Here is a technique for reducing the number of links to any particular topic while still providing the reader with the ability to browse all related topics: Create separate menus of related topics. In other words, do what programmers do: Collect oft-repeated ‘code’ (collections of links to related topics) in a stand-alone ‘sub-program’ (a menu in this case) rather than repeat the same list of hyperlinks in several places. In each affected related topic, include a reciprocal link to the applicable menu of related topics. As well as reducing clutter in each related topic, it reduces the maintenance burden if anything changes. That is because you need only change the link in the related topics menu rather than in all the places that you want to connect via that relation. The cost of this refinement, which is borne by the reader unfortunately, is that he or she has to make an extra click — to the applicable related topics menu.
Incidentally, I feel sure that this or a similar technique must be widely known and used somewhere, likely in programming documentation, but it does not seem to be widely known among general technical authors.
An example page containing several links to such related topics menus is Hang gliding 1975 part 2 on my History of hang gliding web site. The first such link on that page is to the Sport Kites/Wills Wing of California menu. That menu contains many links, some or all of which would otherwise need to be included in Hang gliding 1975 part 2 and the other pages that also refer to Wills Wing. That would cause a maintenance burden if any of those linked pages are moved or have their titles reworded.
Adding menus reduces the number of links that must be maintained
In the example in the accompanying illustration (where I use color to help clarify which link goes where) four topics are related. If you change one (either its heading wording or structural position) you must then correct the link to it in the other three related topics. However, with a dedicated related topics menu, you need only correct the link in that. (In addition, you would need to correct the link to it from the table of contents if that is manually maintained, but you would need to do that anyway.)
As of this writing, my Sport Kites/Wills Wing of California menu has 19 main links. If one of them needs amending, it needs to be amended only in that menu. Without a separate menu, the amount of editing necessary is far greater, potentially 18 links (19 minus the unnecessary link to itself) in many pages must be amended. However, how are you going to find them? Unless your ‘authoring’ system can generate a report of specified links, you cannot guarantee that you have no broken or wrongly worded links.
The benefits to the reader of a better maintained web site, document, or help system far outweigh the inconvenience of the necessary extra click.
Building on relatedness
Where you have several menus of related topics, consider using them as an alternative way in to your material for the reader. That is, alternative to the primary structure of your document, web site, or online help system, which is normally a contents list (of links).
An example of such a menu of relationship menus is the Hang gliding related topics menus section of the main History of hang gliding menu. Such a list has something in common with an index (in a book or web site) but it is ‘manually’ constructed and, hopefully, more useful than an automatically generated index.
Brave Guys and Beautiful Dolls 