Advertisement
  1. Computer Skills
  2. Documentation
Computers

How to Create a Professional Technical Document—Part 2

by
Difficulty:IntermediateLength:MediumLanguages:

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.

create-subject-and-article-description
Create subject and article description

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.

create-step-title-and-paragraph-text
Create Step title and Paragraph Text. 1. Step title 2. Paragraph text box

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.

paragraph-formatting-option-clarify
Various paragraph formatting option in Clarify

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.

code-formatting-clarify
Code formatting options in Clarify

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.

take-screenshot-from-capture-button
Taking screenshot from the Capture button

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.

screen-capture-tool-clarify
Screen capture tool on the screen. It includes some keys to make screenshot workflow much faster

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.

rotate-image-clarify
Rotate an image in Clarify

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

crop-image-clarify
Crop an image in Clarify

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.

type-of-line-annotation-tools
Type of line annotation tools in Clarify

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.

resize-canvas-through-handles
Resize canvas of an image through handles

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.

resize-image-through-handle
Resize image through a handle located at the bottom-right corner

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.

resize-image-context-menu
Resize image through a context 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.

creating-substeps-clarify
Creating sub-steps in Clarify

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.

auto-number-steps-clarify
Auto number steps in Clarify

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.

exclude-a-step-clarify
Exclude a step in Clarify

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.

auto-number-substeps
Auto number substeps in Clarify. If this feature is not working, then it's probably a bug

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 LinePicture frame, and Rounded Corners.

add-image-border-clarify
Add image border in Clarify. 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.

automatically-scale-images-clarify
Automatically scale images in Clarify without the need of an image editor

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.

adding-multiple-images-to-a-step
Adding multiple images to a step is easy and without fiddling around apps

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.

adding-multiple-images-in-single-step
Adding multiple images to a single step. If you have to take screenshot of the same area multiple times configure the Repeat Last Screenshot hotkey

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.

replace-image-clarify
Replace image in Clarify 1. Replace image icon 2. Replace icon near 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.

change-media-type-in-step-inspector
Change media type in step inspector 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.

paste-embed-code-in-box
Paste embed code in the box. Choose the embed code from the Youtube video

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

add-image-to-see-html
Add an image to view HTML 

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.

add-anchor-tags-to-steps
Add anchor tags to steps in Clarify document

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.

share-accounts-in-clarify
Create sharing accounts in Clarify

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.

html-template-clarify
Customize HTML template in Clarify

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.

email-template-clarify
Email template in Clarify. Choose the email client you prefer

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.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.