Page Comparison

(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

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

    • Accept and assign revision request

    • Refer for new documentation

    • Integrate existing documentation on the topic

    • Defer to a later date

    • Reject the request

    • 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

  • ISSUE: Need a formalized process for assigning responsibility for User Manual sections to committee members. This could happen at the beginning of a User Docs term.

• ACTION: Committee member makes changes but does not publish

  • Committee member makes changes, highlight the backup 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)

  • ISSUE: Do we have a style guide or template for new documentation in the User Manual? It would be helpful to create one for guidance for future sub-team members…

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

    • 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

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

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

• ISSUE: How often would we do this? After each major release? 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, or additional steps may be determined.