UAC Documentation - Review Process

Owned by Kevin Clair
Last updated: Apr 06, 2020
2 min read

(subject to change and clarification; this is meant as a starting point for discussion at the February User Docs meeting)

The possible pathways for revision requests:

  • Committee revision proposal

    • As part of new release (edits passed along from Testing, Tech Docs, or other group, or determined from review of changelogs)

    • As part of committee work (issue or new documentation need identified in the course of other committee work)

  • Community revision proposal

    • Via user manual comment

    • Via request

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

  • ACTION: Committee review leading to one of the following outcomes:

    • ISSUE: What are the possible outcomes of committee review?

    • Accept and assign revision request

      • Assign and communicate using ticketing system (see work plan item #4). Further discussion about this is tabled until later in the spring.

    • Refer for new documentation

    • Integrate existing documentation on the topic

    • Defer to a later date

    • Reject the request

    • Change without tracking (fixing typos, etc.)

      • This covers most community requests we’ve seen so far. They are not worth the overhead of a ticketing system.

    • Others??

    • ISSUE: Do we need a ticketing system for assigning and communicating out about revisions? If so, what should we use?

      • This is work plan item #4, which we’ve tabled for now

      • Most of our community requests have been small changes, not worth the overhead of a ticketing system to address them.

  • ACTION: Assign edits to committee member

    • Responsibility for maintaining and reviewing sections of the User Manual will be assigned at the beginning of each User Docs term. Sections that have been left vacant due to committee turnover will be re-assigned based on member preference or assignment by the User Docs chair. Each committee member will be assigned 3-4 sections for which they are primary manager, and an additional 3-4 sections for which they are the secondary reviewer of additions and revisions.

  • ACTION: Committee member makes changes but does not publish

    • Committee member makes changes, highlight the backup secondary reviewer to alert them that changes have been made

    • Highlight the changes that have been made to a page so it’s easy for the reviewer to see what has been changed without looking at revision histories

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

      • Include a mechanism for paging forward and back between different pages in the User Manual, in the order in which it is published appears

      • Include guidelines for structuring pages, integrating outside materials (such as LYRASIS Library videos)

  • ACTION: Peer review from additional committee member

    • ISSUE: Need a formalized process for assigning responsibility for peer review. Should committee members have specific responsibilities for certain sections, or should we assign responsibility ad hoc based on availability?

  • ACTION: Publish changes or refer back to committee member for further revision

  • ACTION: Archive previous versions of the User Manual (in accordance with previous versions of ArchivesSpace)

    • To do after each new release

    • ISSUE: How would we technically go about archiving previous versions of the User Manual in Confluence?

Some steps may not be necessary for all pathways. Additional steps may also be required.