How to Create a Professional Technical Document—Part 2

Creating a Technical Document

You’ve got a new Mac and want to setup the Internet to access the Web. You fear that you might forget the steps, or may be helpful to others. In this example, I’ll create a simple, step-by-step technical document and save it as a PDF document.

1. Add the Subject and Article Description

Write the Subject and a brief Article Description. It should be short, clear, and precisely tell the things you want to show, in this case you want to setup the Internet on a Mac. The Subject line appears on the sidebar of the Clarify dashboard.

Click File > Save As and select the folder where the file is to be saved. By default, it selects the subject of the Clarify document as a filename with extension as .clarify and saves it in the Clarify Documents folder.

2. Add a Step Title and Paragraph Text

Click the + symbol to add a new step. Write the Step Title and paragraph text in their respective boxes. 

If you make a mistake, click the box to edit it. When you add a Step Title you’ll see the step title in the sidebar of the Clarify dashboard.

3. Format the Paragraph Text

Clarify offers a number of options for formatting the text. The format bar appears when you select the paragraph field box. Click one of the icons to change the format of your text. You can choose from Bold, Italic, Bullet list, Link, Superscript and more. 

When you press the return key, Clarify will create a new paragraph. Clarify adds spacing between each paragraph like you’ll see in text on a website.

Clarify also lets you format code as entire blocks of code or as individual words within a sentence. To mark a word or two as code, select the word and click Format as code button from the formatting toolbar.

When you export the Clarify document as HTML, the text will be enclosed in <code>...</code> tags. Select the entire paragraph and click Format as code, to convert the text to a code block with the output enclosed in <pre><code>...</code></pre> tags.

4. Taking Screenshots

You have three options for capturing images 

1. Capture button in the Clarify app
2. Capture button from the menu bar, or 
3. Keyboard shortcuts

Go to Clarify > Preferences and in the General settings configure the hotkeys.

When you press the Capture button screen capture tools will appear on the screen. Drag over the area you want to capture and press the Return key. Press the Space bar to capture a full window. Press the Space bar again to go back to region capture mode.

Press R to cycle through the previous regions you have captured. It is useful when you want to capture the same area of the screen over and over again. Press C to show or hide the cursor while taking screenshot.

5. Doing Basic Tasks With Images

Clarify provides many options to manipulate images: rotate, crop, use basic annotation tools, resize images and the image canvas. 

To rotate the image, click Edit > Rotate Image.

To crop the image, click Edit > Crop Image. Click and drag over the area you want to keep and press the Return key.

You can choose from a number of annotation tools. Select the image and click the type of annotation tool you want to use from the formatting toolbar: Line tool, Square tool, Circle tool, Sequence Numbering tool (you can customise the starting sequence), Text tool and Blur tool.

Clarify has three options to resize images. It has four handles around the sides of the image editor. Click and drag any of these handles to change the size of the canvas. You cannot crop an image using these canvas handles. 

Drag and hold the Option key to resize all the sides of the canvas equally.

Use the image resize handle located at the bottom-right corner. Click and drag this handle to resize the image. Press and hold the Option key to resize the image in 10% increments.

For precise control over the image size primary-click on the step image and select Resize Image…. If the step has multiple images then you must select a particular image and then resize them through a contextual menu.

6. Creating sub-steps or nesting steps

Clarify has the ability to create sub-steps. A sub-step is indented under the parent step and can be one level deep. When you export the document, a sub-step tile will appear differently in a small font size, sub-step numbering (if you enable it). At first, create the usual step as described earlier.

Select the step that you would like to make a sub-step. Go to Document > Move Step menu and move the step right to indent it. Move the sub-step up or down to organise the technical document, as required.

7. Auto-numbering the Steps

When the technical document involves a number of steps then you can prefix them with a number. Clarify will auto-number steps, click Document Inspector and check Auto-number Steps. All other steps will be automatically prefixed with numbers.

To exclude a step from getting a prefix, click the Step Inspector and tick Exclude from Auto-number. That step will no longer be prefixed with a number.

There may be situations where you don’t want to auto-number the top level steps, but just the substeps. To do that, click the Step Inspector and check Auto-number substeps. Only the substeps will be prefixed with numbers.

8. Performing Advanced Tasks With Images

Clarify includes some sophisticated features to manipulate images. Although these features are available on other image editors, having those in Clarify makes the process of creating technical document much faster. To add a border around images, select the steps you want to edit.

Click the Step Inspector and within Image Settings section change the Image Border you want to add for the images. You can choose from Line, Picture frame, and Rounded Corners.

Clarify can automatically scale the images and reduce them if they are too tall or wide.

Click the Document Inspector and check Auto scale images. Set the maximum height, or width of the image or both.

Adding multiple images in a step is a time consuming process too. Click the + sign located just to the side of canvas handle. 

Take the screenshot, and you’ll find them included in the step.

If you’ve configured Repeat Last Screenshot you don’t have to bother about screen capture tools. The image add just below the top image, and so on.

If you wish to replace an image for a particular step, then select the image you’d like to replace, then click the Replace Image icon in the top left corner. 

Or, click the Replace icon located next to canvas handle.

9. Embed a Hosted Video into a Step

A technical document will be easy to follow if you include a video. With Clarify you can embed videos hosted on video services such as YouTube easily into the steps. 

Select the step, click on the Step Inspector and change the Media Type from Image to HTML.

On doing this you’ll see a box for inserting HTML code. Go to YouTube, and copy the embed code of the video. Click Preview to see the preview of the HTML.

Some export formats can’t display the HTML for a step. Click on the Image tab and add an image, for these type of export formats. 

You have to always use the image representation, when exporting your Clarify document to Word (DOCX extension).

10. Add Anchor to Steps in HTML Output

You can add anchor tags to steps that will assign as the id property in HTML output. This can be useful for linking directly to specific steps when you share a Clarify document to the web. 

For example, if you set the anchor name for a step to special-step and if your Clarify document URL is

http://www.myblog.com/my-article.html

then you could link directly to the step by adding #special-step to the URL:

http://www.myblog.com/my-article.html#special-step

To add anchor tags to a step, select the step you want to edit. Click Step Inspector and within Step Settings set the anchor name. 

When setting up an anchor name, use only letters, numbers, hyphens or underscores.

Note: If you don’t set an anchor for a step then Clarify will automatically generate tags based on internal id which Clarify assigns to steps when you create them. This anchor tags will remain same each time you export the Clarify document.

11. Export and Share the Clarify Document

Go to Clarify > Preferences and click Share. Click the + button and choose the sharing account for export targets. A sharing account can export to Clarify-it.com, WordPress and Evernote. You can also export your Clarify document as PDF, HTML, and Word.

For sharing accounts you must have an account and authorisation. For PDF, HTML, select or customise the template you want to use each time.

You can customise the template for PDF, HTML. Email, and Word. In HTML template you can choose from a number of templates: Basic, Chrome, Corporate, Markdown, Technical and even custom HTML template. 

Select the logo and set the image dimensions for this template. Click the Preview button to see the template you customised.

You can also customise the email template in a same way. Since it’ll be using PDF, you can customize the PDF template and select the email client: Apple Mail, Postbox, Outlook or Airmail. Click the Preview button to see the template you customised.

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've shown you the 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.