O'Reilly logo

Practical Development Environments by Matthew B. Doar

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

File Formats for Documentation

This section describes some of the commonly used formats for documentation files and discusses the strengths and weaknesses of each file format. Some formats (such as XML) are more common as source formats—that is, the files where the raw content is added. Other formats (such as PostScript and PDF) are more often used as release formats—that is, the files that are available for customers to use. Only a few formats (such as raw text files) are used as both source and release file formats.

Tip

Current best practice is to provide documents as both HTML web pages (for fast access) and PDF (for downloading complete documentation packages and for printing). It's helpful if you provide a single web page where all the different formats for your documentation can be downloaded, so that people only have to refer to a single URL. For example, http://www.example.com/myproduct/docs, not http://www.example.com/myproduct/pdf/manual and http://www.example.com/myproduct/html/manual.

Some common requirements of a file format and the tools that support it are:

  • Typeset printing, often using different file formats, sizes, and layouts

  • Online viewing, often with hyperlinks

  • Images interleaved with text

  • Searching documents for text or formatting

  • Support for non-English languages and characters

  • Comments that can be mixed with text for reviews but that don't appear in the final product

  • Joining and splitting files

  • Generating lists of the differences between versions of the document, or ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required