This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- The Linux Foundation
- Technical writer:
- xiaoya
- Project name:
- Build Documentation for CHAOSS D&I Badging Project
- Project length:
- Standard length (3 months)
Project description
I put the main content in the following: The main goals are enriching the document-related works within the workflow, write a community-faced D&I badging documentation, and host the multi-language processed documentation on specialty platform, which can be separated into the following micro tasks: Update and integrate the current PR template in the use of more D&I metrics and diverse the questions. Draft a conceptual overview to introduce the D&I badging program Draft the applier guidelines using JOSS docs as a reference Draft the reviewer guidelines using JOSS docs as a reference A document explaining different roles and respective responsibilities throughout the workflow. A document explaining how GitHub probot is applied for the workflow A contributor guideline to show how a newcomer can contribute either the project or the document. Help with the translation work of documents, check the performance of the automatic translation especially in Chinese, and do manual translation works if necessary. Organize the documentation in a multi-language format based on the translation work. Use Gitbook, Read the Doc, or GitHub Wiki to host the document.
Deliverable 1. Enrich the project and event PR template with more metrics and diverse questions. This deliverable includes all the document-related work within the workflow, particularly the PR template prepared for applicants to complete, this is what I think the core component of the workflow as it plays a decisive role on reviewers evaluation, so the form and content of questions will be perfected throughout the construction of the workflow, and I will deliver this from the following points: Basing on different types of events or projects Combining with more D&I metrics Using diversity ways of questions with requiring of proof-based answers
Deliverable 2. Below is a draft community-facing documentation structure
Overview of the D&I Badging
Introduction
Goal
Badge levels
Applying for a badge
Apply for event badge
The event PR template
Apply for project badge
The project PR template
Reviewing
How to become a reviewer
D&I Badging Conflict of Interest Policy
Review criteria
Review checklist
Roles and Responsibility
Applicants - Create PR
Reviewers - Review PR
Moderators - To have a look at reviews and review assignments
Maintainer - Final Check and PR merge
The Probot
D&I Badging Code of Conduct
How to contribute
Deliverable 3. Organize the docs in a multi-language format and host them on platforms like Read the docs or Gitbook.
In the current workflow, some automated translation works are being explored, I will help with checking how well the result of translation is performed especially in Chinese, such as the correctness and fluency of translation. The document will exist as a format, I will investigate the technical docs hosting platforms like Read the docs, Gitbook and GitHub wiki, and choose a best-suited platform to host the open community faced documentation.