Samvera Community Wiki
Doc IG Project Board - Overview and How-to
How to use the “Documentation Tasks” Project Board
This page covers how the Doc IG’s Project Board is organized, and how to use the board.
Link to the Project Board in Github: "Documentation Tasks”.
In this page:
Goals for the Project Board
Make it easy and low-friction for anyone who notices a Samvera documentation need to create a draft issue for their request, and add it to the Doc-Tasks board for triaging.
Provide a framework that the DocIG can use to organize submitted requests, so that the drafts are "Ready to Work" by community documentation contributors.
Overall: make documentation needs and requests approachable for Samvera community members to work on and resolve.
How to submit a documentation request in the Project Board
Please create doc requests as a "Draft" in the Project Board.
To create a new Draft:
In the bottom-left corner of the board, click on "+ Add item" at the bottom of the "Backlog" column.
An input modal will open, as in the screenshot. Start typing in the modal to get the "Create Draft" option to appear. Then click on "Create Draft".
The new Draft will then create immediately, and will appear in the bottom of the Todo column.
You can then open the new draft to edit it, by clicking on the Draft's Title from the Todo column.
What to put in a draft for a documentation request
If possible, please include the following information to make the request easier to work on and complete. Don't worry about creating a perfect description though - the most important thing is just to report the problem. It's OK if all you can do is a quick note and a URL to point the DocIG at the problem. The DocIG will take it from there and prep the draft so it’s ready to work.
Include if possible:
Brief description of the documentation gap, inaccuracy, or other problem you’re reporting. (Documentation gap = we don't have this, and we need it. Inaccuracy = an existing doc is incorrect, incomplete, or needs some other improvement.)
Which Samvera project is this? (Hyrax, Hyku,etc. )
If this is a problem with an existing doc, the URL for the doc
(optional!) proposed solution - if you have an idea about what the fix should be, feel free to include it. Not necessary though! Feel free to submit a problem with no ideas for fixes.
Project Board Workflow: Columns and Labels
Overall workflow for the “Documentation Tasks” board
Anyone in the Samvera community can create a request on the board. Please create Documentation requests as "Drafts". (See above section for details on how to create a draft.)
Workflow Columns
“Backlog”
All incoming documentation requests and ideas go into the Backlog column to start. Items here may not yet have been prepped as issues, so they may not have complete information.
“Todo”
Items in the “Todo” have been identified as priorities.
The DocIG team preps drafts in Todo, so that they are "ready to work". Once a draft is prepped and ready to work, DocIG moves it to the Ready column.
“Ready”
From the Ready column, anyone in the Samvera community can select a request to work on. When you select a request and start work on it, move it into the "In Progress" column.
"In Progress"
Requests stay in the "In Progress" column while they're being worked on. If a question or blocker comes up, move the request into the "Questions/blockers" column for additional help and resolution.
“Questions/blockers"
Requests stay here while questions/blockers are resolved. Once resolved, requests are moved back to "in Progress" until they're completed.
“Done”
When you’ve completed work on the request, move it to the Done column. You can decide when it’s done! No need to get anyone to review it. Feel free to decide “good enough for now”, and move it to Done. It’s also fine for you or someone else to create a followup draft for next steps, if you want call an issue “done” and also put in a request for additional documentation work that you can see will be needed.
More details on workflow steps
Prepping drafts for “Ready to Work”
To make requests “Ready to Work”, the DocIG does the following:
Title and Problem Description: expand or clarify, if needed
Add ‘required’ labels:
SamveraProject: the project this documentation need relates to.
Options: hyrax; hyku; bothHyraxHyku; bulkrax; valkyrie.
Audience: this documentation’s primary users or intended audience (who is it written for?)
Options: Dev/server admin; Repo manager / librarian (managers, editors, depositors); End user; everyone.
doc-location: the location where this documentation need was found or will reside.
Options:
HX-confluence. The "Hyrax Documentation Home" area of Samvera Confluence.
HK-confluence. The "Hyku Documentation" area of Samvera Confluence.
HX-gh-wiki. The GitHub wiki of samvera/hyrax repo.
HK-gh-wiki. The GitHub wiki of samvera/hyku repo.
other. Such as: the Hyrax or Hyku project websites, youtube , or elsewhere
If relevant, add ‘optional’ labels:
Workflow (optional): Tagging for various kinds of followup by the DocIG.
Options: triage, IGdiscuss.
Events (optional): Tags for issues that would be good candidates for various community events, like Documentation Sprints, or for beginning docs-writers.
Add details for “Questions/blockers”
When moving a request to this column, if possible please add details about what is blocking progress.
If the request is a “github Draft”, it's not possible to add a comment, so just add the blocker details into the main description field of the draft.
If the request is a “github issue”, add a comment to the issue with details about the questions/blockers.
Also feel free to ping someone for help by including their github username (@username)
Template for creating a documentation request
There is a template in the Doc Tasks board that you can use for creating a doc request if you want to. It is optional! The template is a Draft in the Doc Tasks project board.
The purpose of the template is to provide pre-formatted markdown text that you can paste into a new github Draft, and then fill in specifics about the problem you’re reporting.
To use the template:
copy the text from here: “[START ACTUAL TEMPLATE - COPY/PASTE FIELDS BELOW]”
down to here: “[END OF TEMPLATE]”
and paste it into your new Draft request
Link to template (Draft in the Doc Tasks project board): “template for Docs issues [WIP]”
Next steps (in progress)
Also:
Roles for working on documentation projects within the DocIG
note for future - points to include in issues:
If some of the Hyku stories in Ready are new and don’t exist – recommend to indicate as part of the story? Or if something is an update or correction, indicate that?