Samvera Documentation Working Group

Owned by Bill Branan
Last updated: Dec 10, 2019 by Andrew Myers

NOTE: THIS WORKING GROUP HAS CONCLUDED AS OF JANUARY 2019

(See Conclusions of the Samvera Documentation WG)

Scope & Objectives

This working group has been chartered to implement concrete improvements to developer documentation within the Samvera Community. These improvements were identified during LDCX^8 and the Hydra Developer Congress held on March 27-31, 2017 at Stanford.

Some work has already been completed toward those improvements, and it was concluded that there was sufficient interest and capacity to setup a working group to organize the remaining work.

Definitions:

  • inline documentation - YARD documentation within code comments.
  • instructional documentation - Any documentation available on the web that is not YARD documentation.

Objectives:

  1. Increase inline documentation coverage and improve quality for repositories under https://github.com/samvera.
  2. Establish http://samvera.github.io as the primary home for instructional documentation.
  3. Define community expectations for coverage and quality of documentation.

Deliverables

Improving inline documentation

  1. Choose one or more tool for measuring coverage and quality of inline docs.
  2. Use metrics from chosen tools to establish achievable targets.
  3. Achieve the targets.

Improving http://samvera.github.io

  1. Implement a theme and layout that provides easier discovery and navigation than current options (e.g. the Duraspace Wiki).
  2. Reorganize existing content on samvera.github.io, preserving any legacy links.
  3. Identify instructional documentation from other sources that should be migrated http://samvera.github.io, archived somewhere, or deleted.

Defining community expectations for documentation

  1. Propose a policy for setting, and maintaining, a threshold of inline documentation coverage and quality.
  2. Propose a policy for where instructional documentation should be created and maintained, and where it should not.
  3. Propose contributing guidelines for adding and modifying instructional documentation.


Issue tracking

We track issues we're working on via github issues and a github project

Sprints and Other Efforts to Improve Documentation

Time frame

Initial timeframe will be May - August 2017. We will meet in early September 2017 to decide whether to re-charter. 

Members


Meeting Times

Doodle poll for our first meeting phone call: https://doodle.com/poll/uxkddrmia6r3332i

Our first call will be Tuesday May 2 at 11am US Eastern time, on the google hangout reserved for this group.

  • Calls every 2 weeks
  • Goal: 30 minutes per call
  • People will take on specific deliverables between calls
  • Every other Tuesday at 11am US Eastern, starting May 2


Meeting Notes

Communication channels

  • Slack channels under the Project Hydra team (samvera.slack.com):
    • #documentation - used for discussion specific to this working group.
    • #dev - used for more general development discussions, and to get developer feedback.
  • "Samvera-Tech" Google Group
  • Samvera Tech Call (weekly)

Resources

NOTE: The Call for Participation (CfP) for this working group was from Monday, April 10, 2017 through Tuesday, April 25, 2017.

NOTE: This is a first draft of the charter. The scope, objectives, deliverables, and timeline may change before the close of the CfP. After the CfP is closed, the working group will move forward based upon the version of the charter at that time. Any further changes will only be made by consensus of the working group.