User Documentation Review Process

The possible pathways for revision requests:

• To support a new release (edits passed along from Testing, Tech Docs, or other groups, usually facilitated by the Community Engagement Coordinator)

• Community requests (via user manual comment, via request received through Community Engagement Coordinator, feedback from querying users, etc.)

• Efforts by the User Documentation Sub-Team to keep manual up-to-date (reviews of pages undertaken by the team)

For each of the pathways by which a revision request might arrive, the following steps will be taken:

• A team member is assigned a page to edit

  • Community requests received via manual comment should be addressed by the primary page watcher.

    • At the start of each term, each team member will be assigned pages for which they will serve as primary and secondary watchers.

    • Team members should watch pages they are responsible for using the Confluence watch feature. Once they are watching a page, they will be notified of any community comments on the pages.

  • When extensive revisions are needed for several pages, work may be assigned among all team members.

• The team member makes changes but does not publish until it has been reviewed by another team member.

  • If changes are made due to a change in function in a new version release, the existing page should be versioned before editing.

  • Changes that have been made to a page should be written in red so it’s easy for the reviewer to see what has been changed without looking at revision histories.

    • If you are deleting text, use the strikethrough feature rather than deleting the text.

  • Refer to the style guide for information on page creation and maintenance.

• Team member notifies the secondary watcher that edits have been made and asks them to proofread the page.

  • Secondary watchers should be notified using the “Invite to Edit” feature in Confluence. Inviting someone to edit a page will send them an email that includes a link to the page and any message in the invite. Primary watchers may want to invite themselves so they can refer back to their invite. If the changes require a lengthy explanation then an email may be sent instead.

  • Primary watchers should also notify secondary watchers via email, as Confluence alerts don’t always go through or are sometimes missed.

• The secondary watcher reviews the page and provides feedback.

• Team member changes any red text to black, deletes any strikethrough text, then publishes the page.

Additional tasks

• After completing edits to a page, update the User Manual Review Google Sheet. Find the appropriate tab and in the “last reviewed” column, enter the month and year that the edits were done.

• When editing pages remove any old copyright or last updated information at the bottom of the page. This is a holdover from the earliest iteration of the manual.