In this part, I will discuss how to enrich the procedure with links and media. Read the rest of the parts here. Screenshots Screenshots can be much more informative than loads of text, but make sure that they are: Relevant. Sometimes a screenshot that presents a completely different or overloaded screen may be more confusing than the missing screenshot.
Up-to-date. Outdated screenshots may contain irrelevant information and confuse users. Each step should have one relevant screenshot that is close to the step it describes. Use the links from other steps of the procedure to return to previous screenshots. Links When using links, keep in mind in which form will the document be presented to the user. For hypertext-only documents, use hyperlinks to return attention to the steps or pictures provided earlier in the procedure. Also, they are helpful in letting users know about repeated actions. If the document can be potentially printed, take a little care about the user: add simple text links, for example: Go to step 2.
Repeat steps 2 and 3. You may want to combine text links with hyperlinks to make the procedure comfortable in both printed and electronic forms. Types of instructions – pics or videos There are many ways to explain complex tasks and the text is not the most convenient of them. You may use other media as well, for example, images or video. A short video clip or meaningful picture may be way better than even a short procedure. Different media may complement each other as well, letting users see the procedure in different ways to learn faster. Multiple ways to do the same task Usually, there are several ways to do the same task. Most users will be comfortable with the shortest and easiest (most accessible for everyone) way. Alternatively, if the target audience is not experienced, it would be better to provide the safest (fail-proof so to say) way to achieve the result. There is no need to describe all the ways if they allow the user to achieve the exact same result. However, it could be beneficial to leave a short note of existing workarounds (just to make sure the user has options to choose from). You may wish to add the criteria for selecting the preferable procedure to the Style guide, and they may include other criteria, like, for example, keyboard-only steps. Describing UI No doubt, when creating a procedure, you’ll have to add some button and window names, menu options, and labels. They make procedure text precise and useful. On the other side, do not overuse them as you will have to keep all UI labels up-to-date. This means, constantly reviewing the instructions and watching the development updates. Unless you have a nice script for that – reduce the number of labels to support. Some style guides say it is not a good practice to describe the position of the UI element with the words like “in the upper left corner of the screen”. I think this idea can be argued. If the interface is nice and clean and the element you mention is easily visible on the screen – then yes, you can use the label only to guide the user. On the other hand, if the interface is overloaded (which may be not the best work of the UI designer, but it is how it is), the short and understandable direction will reduce the time required to find the element. Some best practices: It might be helpful to provide short videos of complex and important procedures.
Sometimes one picture can replace the whole procedure.
Remember – always keep in mind if you need your documentation to be paper-friendly. In this case, you may wish to replace the video with a QR code.
Make sure that there are no technical or organizational restrictions for using certain types of media in your documentation.
Provide links to access media files from relevant procedures and from the parent website as well – this may help to complete the task quickly. Conclusion To write the procedure: Understand the task clearly.


Examine all the ways how you can do it in your program.


Break it down into steps. Drawing a flowchart may work wonders.


Examine media limitations and style guide recommendations.


Start writing. Note complex steps.


Add images, charts, and links.


Review your procedure. Check the basic points:

Length.
Complexity.
Matching UI labels.
Consistent style.
Errors and bugs.



Check the results.


Go through the steps. See if it works. It may be beneficial to use the help of the QA team to check both the document and the software.


If you find it beneficial (and possible) – add videos and links for further research. Keep in mind that the best procedure (and all its elements) is short, clear, and always up-to-date. In this part, I will discuss how to enrich the procedure with links and media. Read the rest of the parts here. Read the rest of the parts here . here Screenshots Screenshots can be much more informative than loads of text, but make sure that they are: Relevant. Sometimes a screenshot that presents a completely different or overloaded screen may be more confusing than the missing screenshot. Up-to-date. Outdated screenshots may contain irrelevant information and confuse users. Relevant. Sometimes a screenshot that presents a completely different or overloaded screen may be more confusing than the missing screenshot. Up-to-date. Outdated screenshots may contain irrelevant information and confuse users. Each step should have one relevant screenshot that is close to the step it describes. Use the links from other steps of the procedure to return to previous screenshots. Links When using links, keep in mind in which form will the document be presented to the user. For hypertext-only documents, use hyperlinks to return attention to the steps or pictures provided earlier in the procedure. Also, they are helpful in letting users know about repeated actions. If the document can be potentially printed, take a little care about the user: add simple text links, for example: Go to step 2. Repeat steps 2 and 3. Go to step 2. Repeat steps 2 and 3. You may want to combine text links with hyperlinks to make the procedure comfortable in both printed and electronic forms. Types of instructions – pics or videos There are many ways to explain complex tasks and the text is not the most convenient of them. You may use other media as well, for example, images or video. A short video clip or meaningful picture may be way better than even a short procedure. Different media may complement each other as well, letting users see the procedure in different ways to learn faster. Multiple ways to do the same task Usually, there are several ways to do the same task. Most users will be comfortable with the shortest and easiest (most accessible for everyone) way. Alternatively, if the target audience is not experienced, it would be better to provide the safest (fail-proof so to say) way to achieve the result. There is no need to describe all the ways if they allow the user to achieve the exact same result. However, it could be beneficial to leave a short note of existing workarounds (just to make sure the user has options to choose from). You may wish to add the criteria for selecting the preferable procedure to the Style guide, and they may include other criteria, like, for example, keyboard-only steps. Describing UI No doubt, when creating a procedure, you’ll have to add some button and window names, menu options, and labels. They make procedure text precise and useful. On the other side, do not overuse them as you will have to keep all UI labels up-to-date. This means, constantly reviewing the instructions and watching the development updates. Unless you have a nice script for that – reduce the number of labels to support. Some style guides say it is not a good practice to describe the position of the UI element with the words like “in the upper left corner of the screen”. I think this idea can be argued. If the interface is nice and clean and the element you mention is easily visible on the screen – then yes, you can use the label only to guide the user. On the other hand, if the interface is overloaded (which may be not the best work of the UI designer, but it is how it is), the short and understandable direction will reduce the time required to find the element. Some best practices: It might be helpful to provide short videos of complex and important procedures. Sometimes one picture can replace the whole procedure. Remember – always keep in mind if you need your documentation to be paper-friendly. In this case, you may wish to replace the video with a QR code. Make sure that there are no technical or organizational restrictions for using certain types of media in your documentation. Provide links to access media files from relevant procedures and from the parent website as well – this may help to complete the task quickly. It might be helpful to provide short videos of complex and important procedures. Sometimes one picture can replace the whole procedure. Remember – always keep in mind if you need your documentation to be paper-friendly. In this case, you may wish to replace the video with a QR code. Make sure that there are no technical or organizational restrictions for using certain types of media in your documentation. Provide links to access media files from relevant procedures and from the parent website as well – this may help to complete the task quickly. Conclusion To write the procedure: Understand the task clearly. Examine all the ways how you can do it in your program. Break it down into steps. Drawing a flowchart may work wonders. Examine media limitations and style guide recommendations. Start writing. Note complex steps. Add images, charts, and links. Review your procedure. Check the basic points:

Length.
Complexity.
Matching UI labels.
Consistent style.
Errors and bugs. Check the results. Go through the steps. See if it works. It may be beneficial to use the help of the QA team to check both the document and the software. If you find it beneficial (and possible) – add videos and links for further research. Understand the task clearly. Understand the task clearly. Examine all the ways how you can do it in your program. Examine all the ways how you can do it in your program. Break it down into steps. Drawing a flowchart may work wonders. Break it down into steps. Drawing a flowchart may work wonders. Examine media limitations and style guide recommendations. Examine media limitations and style guide recommendations. Start writing. Note complex steps. Start writing. Note complex steps. Add images, charts, and links. Add images, charts, and links. Review your procedure. Check the basic points: Length.
Complexity.
Matching UI labels.
Consistent style.
Errors and bugs. Review your procedure. Check the basic points: Length. Complexity. Matching UI labels. Consistent style. Errors and bugs. Length. Complexity. Matching UI labels. Consistent style. Errors and bugs. Check the results. Check the results. Go through the steps. See if it works. It may be beneficial to use the help of the QA team to check both the document and the software. Go through the steps. See if it works. It may be beneficial to use the help of the QA team to check both the document and the software. If you find it beneficial (and possible) – add videos and links for further research. If you find it beneficial (and possible) – add videos and links for further research. Keep in mind that the best procedure (and all its elements) is short, clear, and always up-to-date.

Writing Procedures Part 3: Enrichment and Best Practices

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

How to Onboard a New Technical Writer

5 Software Documentation Tools That Make Managing Technical Documentation Easier

'Archbee is Built Out of Frustration with Available Tools': Startup Interview with Dragos Bulugean

Beware of Documentation Management. A Techlead's Hell Loop.

Common Mistakes in Engineer-Authored Docs and How to Fix Them

How to Describe Your Technical Issue to Get Quick and Effective Help

How to Onboard a New Technical Writer

5 Software Documentation Tools That Make Managing Technical Documentation Easier

'Archbee is Built Out of Frustration with Available Tools': Startup Interview with Dragos Bulugean

Beware of Documentation Management. A Techlead's Hell Loop.

Common Mistakes in Engineer-Authored Docs and How to Fix Them

How to Describe Your Technical Issue to Get Quick and Effective Help

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps