Adobe 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).


Commercial or Open Source?

We have used several Adobe products for documentation. In the 1990s, we used Aldus PageMaker (versions 5 and 6), with the companion graphics program. All our project User Manuals were below 100 pages. The output was to a PostScript laser printer. At the time, it was a lot more professional than Microsoft publishing products. Adobe acquired Aldus in 1994.

A decade or more later, my daughter registered at uni, qualifying for a student discount. The full Adobe suite was purchased for an Apple laptop. I tried it with an evaluation version, and asked her to convert a file or two, but the older PageMaker 5.0 files could no longer be read in. Fortunately, the graphics work that was lost was no longer required, and most of the automation projects had been upgraded with new documentation.

When we considered moving off LaTeX to the Adobe suite around 2008, the pricing in Australia was much higher than in the USA, so on principle, we did not support them. For large commercial projects, your choices would obviously be different. (We since found that there seems to be a significant “software tax” for Australian purchasers). For us, that meant open-sourced software was preferred.

Fast forward twenty years

Portability and being able to read documentation some years into the future requires careful choices when starting a project. End-users like to receive documentation in Word format, but for decent manuals, this is difficult as Microsoft Word is not a publishing package. The conversion from Word to PDF is unreliable, and LaTeX has a steep learning curve if you want to generate output that looks better than a thesis or journal article.

Content will only be useful to others if available digitally. I prefer PDF for manuals rather than one or two pages of HTML that must be downloaded each time you want to look up how to pass parameters or what the syntax is for some CSS item. Terabyte hard drives only cost slightly more than a printed text book.

Amazon's Kindle and Apple's iPad will change how content providers sell books. To make content available without having to redo everything for different media requires a lot of help. Adobe is well known and there are armies of staff that can be contracted in at short notice. The packages are not simple, particularly FrameMaker, but prices appear to be more realistic in 2014 with the Cloud based versions. This might be due to competition rather than any goodwill by Adobe.

Open Options

Legacy documentation, catalogues, your own gigabytes of “bit-rot” all need to move into some current format. Otherwise you might as well throw it away. Large automation projects, design teams and even public access to projects will require local hosting (intranets) or a combination of web hosting and intranets. Search tools are also essential even if only working on something like the Linux kernel. Document tracking and logging of changes across complete directory trees will be important, but the output must be hierarchical with front-end visualisation tools — not low-level tools like CVS, SVN or similar version control tools.

We have started to migrate off LaTeX to XML and previously dabbled with the Adobe tools. We would certainly be keen to hear what your ideas are, particularly in migrating BibTeX, acronyms or legacy code.

The choice would be Adobe products for documentation where a brochure or manual format is more appropriate. The programming options of InDesign with JavaScript will hopefully generate both PDF and web documentation. Some intermediate format like DocBook and XML might also be useful, particularly for eBooks on the iPad.

In August/ September 2014, Apple annouced the Swift programming language as well as Javascript as their scripting interface. These two might give LaTeX a few more years for automatically generated PDF output at decent resolutions.

We used GIMP for graphics work for many years, but for some clients, Photoshop would be preferred. Whether they purchased a legitimate copy was often questionable — judging by the rates they expected us to work for. Thankfully, with a monthly rental of AU$9,99 for Lightroom and Photoshop, this should be a thing of the past.

At those prices, we are prepared to standardise on Photoshop for photographic work and inserts for web pages plus LaTeX documents. We have not had the courage to get the Adobe full suite, and will stick with LaTeX until something programmable comes out that has better support for cross referencing documents. If you are in a hurry or do not have staff who can write custom software, LaTeX might not be the answer either.

What can we offer?

Small conversions are not worthwhile for either clients or ourselves. If there are large conversions that need to be automated, or custom programs for archeology, we might be able to help. We have been looking at XML for intermediate migration, but the style sheets (XSLT) and huge differences in marked up input make this a very difficult job. The ‘standard’ XML readers do not provide much in the way of debug information when things go wrong, so we wrote some parsers and search functions ourselves, but they are not ready “for prime time” yet.