After we've written documentation for an application, it's important to test it. Documentation testing ensures that the documentation is accurate, up-to-date with the application, clear, and consistent.
1. When to test documentation
i. Check for new versions of tools
At the beginning of each month, you should check to see if new versions of the applications in the Knowledge Base are available. If there are, then you should update our documentation to reflect the new versions.
ii. Check when documentation was last updated
In addition to checking for new versions of applications, you should also check to see when our documentation was last updated.
To do this, go to an application's landing page in the Knowledge Base.
Open the documentation. Look at the date at the top of some pages under different branch pages to get a feel for when the documentation was last updated.
We want to keep documentation up-to-date, so if it's been 2-3 months since documentation for an application or some pages within it have been updated, then you should test it.
iii. Content audit
You should do a content audit every six months to ensure that gifs, links, macros, and other aspects of the documentation work properly.
Veronica can explain this in more detail.
2. How to test
After you've determined which documentation needs to be tested, you can start testing.
Open the documentation in the Knowledge Base.
Follow the instructions (as you would if you were a user) alongside its application.
Start from the first page of the documentation and end with the last page.
i. Keep track of your work
It's important to keep track of your your progress as well as to note what needs to be updated or what updates you've made.
Go to Google Sheets to create a spreadsheet you can use to track your work.
Include 6 columns in the spreadsheet: Date | Name of Page or URL | Issue | No issue | Notes | Resolved? (Y/N)
Write the titles of each page within the documentation in the "Name of Page, Feature, or URL" column. This way you can keep track of which pages you have or have not tested.
Chris Jewell designed this spreadsheet for documentation/software testing. You don't need to worry about the JIRA column for documentation testing. That column is meant for software testing. See the Software Testing guide for more information on JIRA.
When you run into an issue, type X into the "Issue" column of the spreadsheet. Include a brief description of the issue in the "Notes" column, including the browser in which the issue occurred.
If a page doesn't need updates, type X into the the "No Issue" column.
If you run into an issue you don't know how to fix, write a comment below the page you're testing in the Knowledge Base. Notify the documentation writer where you left the comment, and they can address the issue for you.
After you've added a comment, click Save below the text box.
Your comment will appear below the page. Note that anyone with access to the page can read it.
3. What to test
Broadly speaking, you're testing everything in the documentation we've written for an application. What you're specifically testing is to see if our documentation gives incorrect instructions for the application's features, components, and overall workflow.
i. Test the features described in the documentation
If a feature we describe in our documentation is outdated, then we need to update our documentation so that it correctly explains how to use a feature.
For example, NowComment updated the way you can comment on images.
It used to be that you could simply upload an image and comment on it as a whole, but then NowComment made it so that you can comment on details of an image.
ii. Test the workflow described in the documentation
If our documentation describes an outdated workflow for the tool, then we need to update our documentation with the new workflow.
For example, the old workflow for Texts in Mandala used to be
- Add a text
- Create a collection
The workflow changed to
- Create a collection
- Add a text to a collection
iii. Test components described in the documentation
Look to see if buttons, search bars, labels, titles, etc. described in the documentation are now different in the application. If a component is different, update the documentation with the new components.
For example:
- has the application's UI changed?
- has the "save" button changed to "save and continue"?
- is there now a "preview" button?
is the search function different from the way it used to be?
4. Update the documentation
As you test, update the documentation to match the application.
To update the documentation, you need permission to edit. If you don't have permission, contact Chris Jewell and she'll get you set up.
First, log in to the Confluence wiki (if you're not already). Go to the page that needs updating.
Click the Edit button in the toolbar in the top right of the page.
The editor will open. Update the documentation accordingly. Read the Step-by-step guide for information on how to format an SBS guide.
If you're updating a step-by-step guide, note that the Confluence editor is sensitive when a page is tagged with "step-by-step." This tag gives the SBS guides their theme.
See the "Look and Feel" section of the Step-by-step guide for information on the SBS theme.