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.

  • 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.