Point of view
The first thing we look for is the point of view. Too often,
technical writers document the UI. Instead, they should document how users use
the UI in their workflow. If more than one role uses the UI, do the roles use
the UI in different ways? This could mean more than one topic is needed. Are
there best practices or tips that can be added?
Relevant for Today
When functionality is first added to software, it is not
fully tested within the users’ workflow. This is true even if UAT has been
done. As the functionality is used within the workflow, users adjust their
workflow to use the functionality in the most efficient manner.
This workflow can be different than what was envisioned by
the development team, since it can include workarounds for defects or
unexpected behavior. These can be covered in one topic or more than one,
depending on the situation. Sometimes I incorporated unexpected behavior in a
note, other times in a separate topic or troubleshooting topic.
Complete and Accurate
The final thing we look for is to make sure we have covered
the whole functionality. Has anything changed in the functionality since the
topic was first written? Details that were true when the functionality was
first added can be inaccurate now due to defect fixes. Is the breath of the
functionality covered? Now that it has been used within a workflow, do users
use the functionality in a different way than expected? Are more tasks required
to cover the use of the UI within a workflow?
As topics age, we need to review them so we can verify that
they are still current based on how the user includes the functionality within
the workflow of their role. This can include how users incorporate workarounds
or changes to how the functionality was originally planned. As tech writers, we
need to remember that even if the functionality is static, users are always
looking for the most efficient way to do their work. As the workflow changes,
we need to update our content.
