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)

Workflows for revision requests: 

Airtable 

As of March 2026, the User Documentation sub-team began using Airtable to centralize the management and documentation of manage and document team member tasks. Access to the workspace is available using these credentials: 

• The Community Engagement Coordinator, or any member of User Docs, adds revision requests to the Unassigned/To Do stack as they are received. 

• The User Docs Chair regularly checks Airtable to assign tasks to team members by moving the card from Unassigned/To Do to the appropriate team member’s stack and updating the card with the assigned editor (primary watcher), reviewer (secondary watcher), and proposed due date.  

• The Chair will then email the User Docs team to notify them of any new assignments and deadlines.  

• Once the editor (primary watcher) has completed their review and initial edits (as outlined in the following section), they will notify the assigned reviewer (secondary watcher) via email and can move the card to the reviewer’s stack. 

• When the reviewer has completed their review, they will notify the editor of the page by email and can move the card to the Ready to Publish stack. 

• From there, the editor can publish their changes and move the card to the Published/complete stack. 

• The Chair will keep track of the number of revisions completed to include in their quarterly reports. 

• The Future Documentation stack is reserved for Jira tickets tagged with User Docs labels for future ArchivesSpace release candidates. 

• When adding comments or notes to a card, members should include their name or initials to avoid confusion since the sub-team shares the account.  

Jira tickets 

• The Community Engagement Coordinator will add User Docs labels to any ticket that requires revisions to User Manual pages. Then they will add these to the Unassigned/To Do stacks as they are received.  

• When the revision is published (according to the Airtable and revision workflows), the editor can comment the status on the Jira ticket and remove the User Docs label. 

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

• When editing a page, update it to reflect the current Style Guide (i.e., borders/shading around screenshots, sub-record fields in tables instead of a list, etc.).

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

Resolving user comments on a help page:

• Reply directly to the comment thanking the user for their feedback. A copy of your comment will also be generated and sent to the user’s email. Briefly explain how the issue was resolved, including any changes made or why a different action was taken.

• To keep the page from being bogged down with comments, mouse over towards the top of the first comment and click on the check mark icon. This will mark the comment thread as resolved and will remove it from the page.