(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 requestISSUE: 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?
ACTION: Archive previous versions of the User Manual (in accordance with previous versions of ArchivesSpace)
Some steps may not be necessary for all pathways, or additional steps may be determined.