Ewa In the article about how to change your job, I suggested that it might be a good idea to test yourself first before your jump right into a new career.
How can you test yourself for a technical writing position? The best way is to take a piece of software and write technical instructions for it.
Table of Contents
Practice writing technical instructions
If you don’t have an idea what technical instructions you can write as an exercise, here are a couple of ideas:
- Microsoft Excel. Write instructions on how to add and edit Excel tables. Your text should contain the desciption of the Table tab and step-by-step instructions on how to perform the most important actions on tables (adding, editing, deleting). Tip: it’s sometimes handy to descibe complex tabs or menus in a table.
- Microsoft PowerPoint. Write instructions on how to add and work with icons. Include the instructions on how to search for icons and how to add multiple icons at once. Tip: if you refer to a UI element that is marked with a small icon or sign, it’s a good idea to include it directly in your text. For example, “Click on a tick
to select or deselect an icon.” - Confluence. Write instructions on how to create a page on Confluence. Your text should contain the description of the top toolbar, information on saving and publishing. Tip: think about the prerequisites; can the user save a blank page?
- Google. Write instructions on how to use the Advanced Search. Tip: is there a way to use the Advanced Search directly in the search box? If yes, describe it as an alternative method in your instructions.
to select or deselect an icon.”Step 1: Play around with the feature(s)
Start with getting familiar with the piece of software that you have to document. Play around with options, buttons, and settings. Go through the whole process that you have to document, for example, if you are to explain how to add a new page, then go through all steps that are required to do so. Check if there are alternative ways of completing the process. Additionally, try to “break down” the software – if you succeed, then this will be something you can describe in the manual (if you are doing an exercise) or you have to contact your development team (if you already work as a tech writer).
Step 2: Plan your content and create a draft
Now that you understand the software you are going to document, take a moment to plan and think through the whole content. You can ask yourself the following questions:
- How many chapters or sections should I create? Think about each chapter/section as a separate topic. For example: you can introduce the idea of Excel tables in an introductory chapter and then create a couple of subchapters about each functionality related to tables: creating tables, editing tables, deleting/converting tables.
- How should I structure the content? Think about sections, headings, screenshots, and examples. When you start documenting for a company, there should be some guidelines on how your instructions must be structured, so make sure that you know these guidelines before you start your first assignment. If you document as an exercise, you can structure the content similarly to the example below or figure out your own structure that would be the most understandable and easy-to-follow for the users. Remember that clearly marked sections with actionable headings make it much easier for the users to quickly scan the content and find the information they need.
Here is an example of a draft for the exercise on Excel tables:
- Intoduction
- What are Excel tables and why do you need them?
- Advantages of using tables.
- List of topics that you will find in this section.
- Add a table
- Introduction.
- Instructions in a numbered list on how to create an empty table.
- Instructions in a numbered list on how to convert existing data into a table.
- Work with tables
- Introduction.
- Description of the Tables tab in a table with the following columns: section, name of the function + its icon, description, (optionally) link to subchapter with detailed instructions.
- Table operations in subsections.
- Delete or convert tables
- Introduction.
- Instructions in a numbered list on how to delete a table.
- Instructions in a numbered list on how to convert a table to a range.
Step 3: Write an intro
As you can see in the example above, the introductory part appears in multiple places. The reason for that is that typically, the documentation is published on a website and the users may jump into a certain page, for example, from search engine results. That’s why they should always be aware of where they are in the content and what the content is about.
The introduction shouldn’t be very long. It can contain one or two sentences about the feature. If your content is very complex, you can consider creating an outline of it in the introductory part, so that the users know exactly what to expect and can jump into sections that interest them most.
An introductory part is often a good place to write prerequisites: if a user needs to do something before he can use the function, here is a good place to mention it. Similarly, you can add here anything the user needs to be aware of before he jumps into using the feature.
Step 4: Write step-by-step instructions
Typically, there is more than one step required to perform an action in an application. If this is the case, you should use a numbered list.
When you want to enumerate some elements (for example, possible menu options), and there are more than one or two of them, you can use a bullet list.
In a list, you can combine different strategies, for example:
- Use a bullet list inside a numbered list.
- Introduce a table inside a list, for example, if you want to describe menu options that are available in a step.
- Add a screenshot in a list if it’s related to what you describe in a given step.
- Add an info box or a warning box if there is some crucial information that the user should now before they go to the next step.
- Add links or references to related content.
Step 5: Add examples or practical use cases
Step-by-step instructions from step 4 should be generic. You can add some examples within a list, but it’s sometimes a good idea to create a separate example.
An example can also present the most popular use case of a feature or quite on the contrary: you can introduce an additional example with an edge case. It all depends on the feature that you document. Try to think about what would be most useful for the reader. If you already work as a tech writer, you can also ask your team or your PO/PM what are the most popular use cases and then document them in an example.
Do you like this content? Do you want to get notifications about new articles? Like or follow my Facebook page to get notified about new content!
