NOTE: The Call for Participation (CfP) for this working group is open 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.
Scope & Objectives
This working group has been chartered to implement concrete improvements to developer documentation within the Hydra 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.
- inline documentation - YARD documentation within code comments.
- instructional documentation - Any documentation available on the web that is not YARD documentation.
- Increase inline documentation coverage and improve quality for repositories under https://github.com/projecthydra.
- Establish http://projecthydra.github.io as the primary home for instructional documentation.
- Define community expectations for coverage and quality of documentation.
Improving inline documentation
- Choose one or more tool for measuring coverage and quality of inline docs.
- Use metrics from chosen tools to establish achievable targets.
- Achieve the targets.
- Implement a theme and layout that provides easier discovery and navigation than current options (e.g. the Duraspace Wiki).
- Reorganize existing content on projecthydra.github.io, preserving any legacy links.
- Identify instructional documentation from other sources that should be migrated http://projecthydra.github.io, archived somewhere, or deleted.
Defining community expectations for documentation
- Propose a policy for setting, and maintaining, a threshold of inline documentation coverage and quality.
- Propose a policy for where instructional documentation should be created and maintained, and where it should not.
- Propose contributing guidelines for adding and modifying instructional documentation.
We track issues we're working on via github issues and a github project
Initial timeframe will be May - August 2017. We will meet in early September 2017 to decide whether to re-charter.
- TODO: Choose a facilitator
- Bess Sadler (Data Curation Experts)
- Aaron Collier (California State University)
- Jennifer Lindner (Art Institute of Chicago)
- LaRita Robinson (University of Notre Dame)
- Andrew Myers (WGBH)
- James R. Griffin III (Lafayette College Libraries)
- Lynette Rayle (Cornell)
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
- Slack channels under the Project Hydra team (project-hydra.slack.com):
- #documentation - used for discussion specific to this working group.
- #dev - used for more general development discussions, and to get developer feedback.
- "Hydra-Tech" Google Group
- Hydra Tech Call (weekly)
- Hydra Documentation Working Group on Github - Repository for issue tracking and other working documents.