Documentation Formatting

by Bradley Nice, Content Manager at ClickHelp — all-in-one help authoring tool

Document formatting is the appearance and visual structure of a document. It’s the mechanics of how the words appear on the page. A well-formatted document should be:

• consistent,
• correct,
• meet stated requirements,
• be reader-friendly.

The visual appeal affects the readers and how they perceive the information, so formatting is essential for any document. It makes information more accessible to the reader by creating and labeling sections (headings), highlighting keywords or ideas (bold, italics, or lists), and making a good impression (professional look, appropriate font choice for the document type).

When you work in a team, some details like slight differences in font size or line spacing are easy to miss. Still, these subtle inconsistencies lower the overall professionalism of your document. In addition, disorganized formatting will reflect on your abilities not in a good way, and your audience may lose confidence in your message.

The best way to go about it is to use templates. However, every company works slightly differently and has different products. There are many ways to format a technical or professional document. The format differs based on your industry and organization. That’s why it’s best to use existing templates and documentation formatting examples to custom format your technical documentation.

Here are some documentation formatting examples.

DOC

DOC is an abbreviation of “document.” One of the most widely known formats. It’s a filename extension for all word documents.

It began as an extension used to signify any documentation with only plain text. Today, it’s more than just a plain text document; Microsoft Word allows using pictures, graphics, diagrams, etc.

If you need to produce a relatively minor technical document Doc will fit you right. However, if your documentation has hundreds of topics, I wouldn’t suggest using this format — minor inconsistencies can mess up the overall document formatting. As a result, when you print the document, it may cause unwarranted formatting issues.

Besides, Doc files don’t support videos or GIFs; you can only hyperlink it or provide a direct link. In any case, the user would have to open another app or browser to watch the video or GIF.

PDF

The Portable Document Format or PDF format was developed in 1993 by Adobe as an alternate way to present documents that can include text, images, and graphs, independent of the operating system, hardware, or application software.

Every PDF file contains a top-to-bottom description of a fixed-layout flat document that includes unique fonts, text, vector graphics, raster images, and other information. Many people find it hard to edit PDF afterward, so the document should be created without any inconsistencies at once.

Nowadays, PDFs include different forms of content that also include logical and interactive structuring elements like annotations, form fields, layers, videos, and 3D objects.

Moreover, PDFs also provide additional encryption options, and you can include file attachments, digital signatures, and metadata.

The fact that PDFs allow all forms of content now make it great for document formatting when it comes to technical documentation.

CHM

Otherwise known as Compiled HTML, CHM is used for software documentation. This format includes HTML pages, an index, and various navigation elements that act as a table of contents.

CHM files are compressed and used in a binary format with the extension. That keeps the document size extremely small while ensuring faster loading times.

It is normally used for CSS and PHP tutorials, software manuals, and legal documentation like the details of a Creative Commons license.

Regardless of the fact that it was designed by Microsoft, CHM formatted files can be opened and viewed by various applications.

It allows for all the basic features like italicize, bold, markup, markdown, and more. CHM is a great technical documentation formatting example because of the navigational properties.

Online Documentation

Online documentation is topic-based information with online access. You can open such documentation on any browser, regardless of the operating system and software.

The critical aspects of online documentation are:

• If you have a stable internet connection and a browser, you can access the documentation online.
• Such documentation supports all forms of visual content elements: graphics, diagrams, videos, etc. These elements are available inside the document immediately.
• Your documentation formatting will remain the same from when you designed it even after publishing.
• You can get several formats for the document. That will help make documentation access easier for different kinds of users with varying systems.
• It’s much easier to use a professional technical writing tool for online documentation.
• You can directly link to other sites, documents, and tools in the documentation itself.

Technical documentation can be of various forms, and depending on the purpose, you should choose the correct formatting. CHM documentation formatting is best for software manuals. Product manuals are better off with PDFs. If you have a website, your best bet is online documentation.

In any case, it’s better to stick with the industry standard because that’s what the users are familiar with.

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors