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).
Portability and being able to read documentation some years into the future requires careful choices when starting a project. How many times has a wordprocessor moved tables and changed formatting without any warnings? Page breaks are often immediately after section headers, and breaking a project up into chapters is not something that comes naturally to standard wordprocessor products. Many versions cannot open previous file formats, and layout is likely to change depending on the templates saved from other unrelated documents. ASCII is pretty universal for English speakers, so standard LaTeX is pretty useful for large manuals that are arranged as separate chapters (per file) with a well organised bibliography (BibTeX compatible). (For languages that require Unicode, see XeTeX). Add-on packages are available for many publishing tasks, but occassionally there are no solutions to features available in commercial desktop publishing packages like the Adobe Suite. Structured publishing will require some programming skills, particularly tracking acronyms, indeces, cross references and database back-end (catalog-type) publications.
LaTeX has served us well for fifteen years to move beyond the limits of creating documents with commercial tools that did not automatically support acronyms, bibliographies or crashed when printing more than a 100 pages. End-users like to receive documentation in Word format, however, PDF and web documentation, or some intermediate format like DocBook and XML might also be useful, particularly for eBooks on the iPad.
Shortly after arriving in Australia in 2008, I contracted on a weekly basis. The projects were fairly small to fill in — one small enough to complete in two or three weeks was pushed through the usual LaTeX and Doxygen run. The LaTeX manual is encoder.pdf (1,3Mbytes), and the Doxygen output is refman.pdf (684 kBytes).
A golden rule is not to have “Under Construction” signs, but for the LaTeX stuff, we have a lot of 100+ pages to sanitize for posting and to reduce the resolution of photographs. These documents may be edited slightly for multi-column output, but for serious work, we will probably move to TeX and create our own classes to integrate with the acronym and other software projects. InDesign seems to create larger sized documents than pdfLaTeX, however, we have previously used PhotoShop and Illustrator for the graphics within TeX documents. We still prefer to use TeX commands for typical diagrams in technical projects (boxes and shapes with good text labels).
The Photoshop and Illustrator packages that the kids used at university
have been really impressive. The prior efforts at generating LaTeX
graphics were challenging — the page below took a while to create.
The programmed nature of TeX helped, plus the output is vector based so it
scales nicely for high quality print. The code to generate the blue bezier
lines without the arrows is
The next snippet of
produced one of the series of labeled boxes (128mm line, 33 vertical lines and some text from a stepped counter). There were about 120 lines of this sort of input; no doubt if you ever used Illustrator, then for less regular diagrams it would be well worth the cost and effort to buy it. The LaTeX package is free, but a single LaTeX diagram in hours would swamp any Illustrator rental costs at a hundred dollars a month — and no, Visio does not compare.
I would hate to have to modify the diagram almost four years after creating it! Remember that you are placing lines at absolute positions and need a long “LaTeX run” to see your handywork. Hopefully you have placed all the points in the correct co-ordinates—not something you can easily visualise in your head. (I overlay a graph paper grid over the diagram when using LaTeX drawing by running one line of an \input of various standard grid sizes I created over the years.) The learning curve was steep, but I free-wheeled back down soon afterwards as it is not something you can do everyday for the fun of it.
We used XeTeX on an Apple Mac platform for a few years. For the past year (2014) we have not done much in the way of documentation, and were hoping that the XML intermediate format would be developed further. In September, 2014, the search for XeTeX showed that SIL International no longer manage XeTeX development. The neat part with a Mac platform was that the fonts available to Apple users would be available to XeTeX, supporting Unicode. There is documentation on dblatex (at SourceForge). A brief scan shows a lot of installation scripts, so expect this to be no different from your marches through the swamps up to now. We are working on small programs to parse XML documents for a website framework, and will return to TeX based systems later. We still have not found easy document cross referencing (across documents), mini table of contents per chapter, or bibliographies per chapter. There are a lot of piece-meal solutions, but running manuals through these is fraught with errors that are hard to track down. You fix one thing, and break a bunch of others.
Figure 1. A screen snapshot at 700 pixels across. The printed version is much better.
© 2014 — Second Valley Software Pty Ltd. All Rights Reserved