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

  To support a 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

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 team)

For each of the pathways by which a revision request might arrive, the following steps could will 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 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 which they will serve as primary and secondary watchers for.

    • 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 revision is needed to several pages, work may be assigned among all team members

• Team 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 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 made in red 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?

...

• Team member notifies 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 will include a link to the page and any message included in the invite. Primary watchers may want to invite themselves so they can refer back to their invite.

• Secondary watcher reviews the page and provides feedback

• Team member publishes page