Documentation

 

Our advice is to always have an ASCII version of your reference design if possible. Simple C programs can sift through this which is not the case with changing proprietary file formats (seldom documented either).


Ox Records in Babylon

Administrative documents:   Early Dynastic III, about 2500 BC probably from Shuruppak (Fara). “The governer receives 14 shekels of silver from 5 persons, and 46 shekels remain unpaid by 13 other persons. The total amount of silver is 1 mina.” Photo taken in the British Museum, London, 2005, almost 4500 years later. I doubt expensive inkjet printouts or file formats will last much beyond twenty years—something the ancients who preferred papyrus were aware of ?

A touch of history

We've written a fair amount of documentation over the years — initially in nroff in the 1980s for a Master's thesis, (on a Zilog System 8000 Unix computer with SCCS version control), followed by Pagemaker in the 1990s (low-cost PostScript laser printers arrived). We adopted LaTeX and doxygen from 2000.

We have written custom programs and scripts for customers to migrate their software or packages to other platforms. For one customer, we even intercepted printer output on the parallel port to migrate their database and stock, as the vendor did not provide any export utilities (for obvious reasons). These projects are rare and difficult to quote. The alternative was to retype in all the stock items, which would have taken weeks and several data entry folk. Most packages now provide export utilities, and when adopting any new offering, the export options should be fully explored, as you have no control of the vendor for future support — the package might become obsolete, the platform may fade away (DEC Alpha, MIPS, Windows XP, etc.), or the acquiring company may no longer wish to provide support (Oracle with Sun Microsystems' StarOffice).

We have explored several systems to try and create both web and print documentation. Adobe was purchased for one of the daughters when she went to uni, and the outputs between LaTeX and InDesign were briefly compared. We were not convinced to migrate to Adobe, perhaps if there was more emphasis on documentation from our customers, then it might have been worth the effort and expense. Our documentation is mainly for source code and end-user manuals. These are not general purpose packages, but custom projects, and for a much smaller audience. We briefly describe our experiences with each of the documentation types via links at the top right of this page.


Not out of choice

Programmers like generating documentation almost as much as customers enjoy paying for it. In Linux and much of the open source offerings, comments appear to be a “sign of weakness in Geekdom”. As HR stroll down corridors with an axe, there might even be less incentive to make yourself redundant by making it easy to move software support offshore. Similarly, the squeezed outsourced company does not want the package returned in-house.

We comment our code for others to continue nurturing it; we have no desire to hide the internals making us the guardians of less interesting projects as technology races ahead. You would also be surprised how often you revisit your own code and labour through it as you never ever thought it would be reused.

Why is documentation important?

The corporate documentation landscape is littered with expensive shelfware that occupies space as the installed software never ends up looking like the specifications — which consumed almost half the budget and time to generate by expensive personnel. Some industries are worse than others (by large margins, but enough said). We've worked on military projects and subcontracted on plenty of embedded projects, but have found the most useful form of documentation to be generated from the source code (by Doxygen as an example), or written as user manuals after the system has stabilised. A full source code listing is also useful for closure as everything is bound with a copy for the end-user and another for our bookshelf.

Disaster recovery, system duplication (reuse), future upgrades and maintenance all rely on documentation. If it does not reflect the current state of your software, then programmers joining your team will take longer to find their way. Similarly, end-users will become frustrated when directed towards the shelfware when things don’t work as expected. The old adage of “Read the manual” is unhelpful — make the documentation interactive in a computer searchable format rather than engage in archeology.

Our plans

We have tried Scribus, Inkscape, InDesign and several other packages with the aim of moving prior documentation into something we can maintain. Commercial packages in the 1990s were expensive. Adobe managed to acquire a couple, (Aldus PageMaker, FrameMaker, etc.) The open software movement wrote office compatible products for Linux. The commercial StarOffice was acquired by Sun MicroSystems, who released it later as OpenOffice. Examples of publishing software for under $50 are PrintWorks from BeLight Software, based in the Ukraine. SketchUp might be a competitor for Illustrator, but trying to import/ export graphics into a publishing package requires a lot of work unless they were written to interface with each other.

From the above range of packages and trials, acquisitions and wildly fluctuating prices, we feel it is important to adopt a package where the content and presentation are separate. LaTeX, HTML with CSS, and OpenOffice XML format do help, but to be able to output for both the web and print, many small programs are required to manipulate XML files.

We are moving into structured publishing; to get control over our years of “bit-rot” that seeps into terabyte drives. Unpublished design files were bound at the end of projects after a brief write up. Any loose papers that were not referenced for six months were jettisoned from filing cupboards to reach “closure”. The bookshelf above represents selected hardware designs (that were bound). Software projects and PDFs may be posted after a cleanup. When we packed up to move across continents, close to two tons of paper, data books and filing cabinets were given away or recycled — only the more important stuff made it across the Indian Ocean.

Our future work will move to an intermediate format suitable for both Web and PDF generation with DocBook, XML and a database for structured publishing. Our early work is locked in older versions of publishing software that can no longer be opened, or was simply discarded as the hardware became fossilized. Our more recent LaTeX derived PDFs have too many high-resolution photos to download over the web. In time we’ll add in low-resolution photos or split the chapters up into articles for individual posting. We now have Photoshop (September, 2014), so excuses are becoming more difficult! The problem is also reformatting for a wider audience rather than yourself.