How to Create a Professional Technical Document—Part 1

A technical document is the result of creating effective technical user information. It either explains how something works or how to use it. It may mean different things to people in different roles. You may need such documentation to onboard new hires, explain new features or as a reference for people not versed in technology.

Writing a technical document needs a number of tools—a screenshot app, an image editor, a word processor for writing instruction and tools for sharing the document. 

Although this is the best protocol for making a technical document, it doesn’t seem right when you lack time or have to periodically update them.

In this two-part tutorial I’ll show you how to use Clarify to create simple and professional technical documents.

• Configure the app to reap maximum benefits.
• Create an in-depth tutorial with multiple steps, images, and text.
• Share the document with other people or web.

Reasons to Choose Clarify

1. Clarify is a cross-platform application available for both Windows and Mac computers. It is compatible with versions from Windows Vista to 10 and OS X 10.7 Lion to 10.11 El Capitan and macOS 10.12 Sierra
2. It lets you create technical document in small chunks and explain them in a step-by-step manner. You can add images, annotate them with visual tools and add text to explain the steps
3. It has an in-built integration of tools to let you share the document over web, email and evernote. You can also save them as a PDF, HTML, and a Word document
4. It lets you create custom HTML and PDF template, so you can focus on the task of creating a technical document and not worry about logos, fonts, colours, header and footer, page breaks and more

Configuring Clarify

Clarify gives you few options to set the technical document as per your needs. Go to Clarify > Preferences. 

You’ll see three preferences: General, Share, and PDF Templates. Each preferences lets you configure multiple parameters.

General Settings

Configure the hotkeys for taking screenshots. To change the hotkey, click Remove and type in the new hotkey. If you prefer big canvas to write your technical documents, toggle Document editor text size from small to large.

Clarify lets you customize the image settings, the way you want. Select the export format as PNG or JPEG (Good, Better, Best). You can automatically generate ALT tags for the images or automatically scale the images, both width and height, as per the style guide.

Share

Clarify offers a number of different ways to share the documents created. You can export to clarify-it.com so others can view documents. You can export the document to the custom WordPress blog or .com blog or save them as a PDF, HTML, or a Word document.

PDF Templates

Clarify comes with four basic templates: Basic, Black and White, Chrome, and Corporate.

If you’ve some specific needs then you can create your own PDF template. Click the + button to create a new custom template.

In the General tab, customise page size and margins, image alignment, content flow settings and more. When generating a PDF document, Clarify adds page breaks in certain locations. Although Clarify tries to keep step content together, you can configure them.

Click the Content Flow menu to configure page break settings. Choose One step per page to add a page break after each step. 

Choose Fit as content as possible per page to put as much content on the page as it can. Use CSS to further control over page breaks.

In the header field you can add a Logo and customise a few more variables. You can add variables like

• [[Document Title]] — The name of the document
• [[File_Name]] — The name of the PDF file
• [[Date]] — The date in the format that your system use
• [[MM/DD/YYYY]] — Month, day and year

In the footer field you can add page numbers and footer text. You can add variables like

• [[Page_Number]] — The page number
• [[Page_Count]] — The total number of pages

In the Fonts & Colors tab, set default font, font size and colour for header and footer, article description, step title, and substep title. If you don’t set a font for a particular object, then it will use the Default Font.

The Custom CSS tab lets you make adjustments to elements that aren’t available in the user interface. PDF templates in the Clarify works on the principle of HTML and CSS. If you’ve a knowledge of both, then you can add many variables to PDF template. For instance

.step-container (
page-break-after: always
)

This CSS tells the PDF generator to always add a page break after a step. You can also add specific font styling to your PDF document by adding specific CSS classes in the document.

.step-title (
font-style: italic;
font-weight: lighter;
)

Some of the classes you can use are article-description, step-title, step-container, sub-step, and step-instructions. At each step you can click Preview to see the final output of the PDF template.

Conclusion

Clarify is a native app for Windows and Mac to create technical documents. It lets you create templates so you can focus on creating a technical document without fuss and managing multiple apps — screen capture tool, word processor, and sharing tools.

In this tutorial, I have shown you how to configure Clarify app to reap maximum benefits and how to setup templates.

In the next tutorial, I'll give a step-by-step procedure for creating a technical document. The app includes a 14-day trial and is available for $29.99. See the pricing details for more information.