This document explains the template contributor roles and other tools and resources that support the template creation process. See the Template Contributing Guide to understand the larger context for these roles and resources.
- Template writing working groups
- Templates coordinator
- Template mentors
- Community reviewers
- Pull request reviewers
Our project is organized into several working groups that meet on a regular basis to work on the project’s key initiatives. One of the best ways to get started with our project is to join and meet with one of our working groups. See The Good Docs Project Working Groups for a list of our current active groups.
If you are a first-time contributor, you are required to join a template writing working group as you work on your first template project.
The working groups that are specifically devoted to template writing are:
🚩 NOTE: As a template writing working group grows, it might need to be broken up into smaller groups. When separate groups should be formed will be left to the discretion of the template mentor leading the group, but the general recommendation is no more than 5-6 participants.
This templateer oversees our overall template development process and provides assistance to contributors working on templates.
The current acting templates coordinator is Aaron Peters.
The templates coordinator:
- Acts as a project manager for all template-related work.
- Oversees the overall template development process and provides assistance to contributors working on templates, such as helping get community reviewers or pull request reviewers to look at template drafts.
- Coordinates and communicates regularly with the template authors, template mentors, community reviewers, and pull request reviewers.
- Ensures each template receives at least three community reviews on their draft when a template is in the feedback phase.
- Acts as a gatekeeper for template quality and, along with a template mentor, makes the final judgment call about when a template is ready to move from the feedback phase to the pull request phase.
- Is authorized to merge template pull requests.
- Tracks whether the ticket for that template can be closed or if additional tickets need to be created to reflect dependent tasks.
To become the templates coordinator:
- You should be a member in good standing in the Good Docs Project community, as defined in our Code of Conduct.
- You should optionally have experience with the template writing process, which is demonstrated by one or more of the following:
- Completing a full template set from beginning to end.
- Serving as a template mentor for at least 2 months.
- You must be nominated for this role by the existing templates coordinator, an existing template mentor, or a member of the project steering committee.
- Receive approval from a majority of members of the project steering committee.
This group of experienced templateers can suggest approaches to challenging template development problems. They lead template writing working groups, which often act as workshops where template authors can receive guidance and mentorship while working on templates.
The current template mentors are:
- Aidan Doherty
- Alyssa Rock
- Cameron Shorter
Template mentors:
- Lead a template writing working group.
- Mentor other writers and give them the tools, perspectives, and resources to help them create high quality templates.
- Are very knowledgeable about the template writing policies and procedures and can answer questions that working group members might have about the process.
- Help connect writers to resources or subject matter experts that can provide feedback on their template drafts.
- Provide assistance to contributors working on templates in their group, especially when they are blocked.
- Coordinate and communicate regularly with the templates coordinator.
- Work with the templates coordinator to ensure each template receives at least three community reviews on their draft when a template is in the community feedback phase.
- Notify the templates coordinator and make recommendations about when a template is ready to move from the community feedback phase to the pull request phase.
To become a template mentor:
- You should be a member in good standing in the Good Docs Project community, as defined in our Code of Conduct.
- You should be an experienced technical writer with good communication and collaboration skills.
- You should be familiar with strategies for leading effective writer’s workshops.
- You should have experience with the template writing process, which is demonstrated by one or more of the following:
- Completing a full template set from beginning to end.
- Participating in a template-focused working group for at least 2 months.
- You must volunteer and be endorsed for this role by the templates coordinator, a template mentor, or a member of the project steering committee.
In addition to the members of template writing working groups, this group of volunteer templateers review templates during the community feedback phase.
🚩 NOTE: At least three community reviews are required for each template, but more are preferred.
Acting as a community reviewer is a good way for an experienced technical writer to start getting involved with The Good Docs Project and provide a first contribution.
Community reviewers includes anyone who is a member of the Good Docs Project, including members of template writing working groups.
Community reviewers:
- Respond to requests from the templates coordinator and/or template mentors when a community member has a draft that needs review.
- Provide meaningful feedback that will help the template produce a high-quality template.
- Encourage both global-level revisions (on the document as a whole) and local-level revisions (at the paragraph, sentence, or word level) as needed.
- Strive to give feedback that is constructive and avoid making comments that will increase defensiveness.
- Be available (asynchronously) to the templateer if they have follow-up questions or concerns about your feedback.
To become a community reviewer:
- You should be a member in good standing in the Good Docs Project community, as defined in our Code of Conduct.
- You should have writing experience or subject matter expertise for the type of document being reviewed.
- You should be familiar with the Conventional Comments theory of labeling feedback.
- Let the current templates coordinator or a template mentor know that you want to volunteer as a community reviewer.
This group of experienced templateers review and approve pull requests to the templates repository.
🚩 NOTE: At least two pull request reviewer approvals are necessary to merge a template into the project.
The current pull request reviewers are:
- Aidan Doherty
- Alyssa Rock
- Cameron Shorter
Pull request reviewers:
- Act as gatekeepers for template quality and assist in making the final judgment call about when a template is ready to merge.
- Apply the template quality checklist to each pull request to ensure it meets the project’s standards for quality.
- Strive to give feedback that is constructive and avoid making comments that will increase defensiveness.
- Be available (asynchronously) to the templateer if they have follow-up questions or concerns about your feedback.
- Coordinate and communicate regularly with the templates coordinator.
- Work with the templates coordinator to ensure each template receives at least two reviews from pull request reviewers when a template is in the pull request phase.
- Notify the templates coordinator and make recommendations about when a template is ready to be merged.
To become a pull request reviewer:
- You should be a member in good standing in the Good Docs Project community, as defined in our Code of Conduct.
- You should be familiar with the Conventional Comments theory of labeling feedback.
- You should be an experienced technical writer who is familiar with our project’s standards for quality.
- You should have experience with the template writing process, which is demonstrated by one or more of the following:
- Completing a full template set from beginning to end.
- Participating in a template writing working group for at least 2 months.
- You must be nominated for this role by the existing templates coordinator, a template mentor, or a member of the project steering committee.
- Receive approval from members of the project steering committee.