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:
- jaskiratsingh2000
- Project name:
- CHAOSS: Create a CHAOSS Community-wide Handbook
- Project length:
- Standard length (3 months)
Project description
PROJECT ABSTRACT:
Currently, working groups within the CHAOSS community have developed their own ways of working and documented their disparate processes to varying degrees. Working Groups includes Common Metrics WG, Diversity & Inclusion WG, Evolution, Risk, and Value working groups which have set up their own participating and working ways and adapted different ways of communication and work culture. These working groups in accordance with metrics have different focus areas and backgrounds which works for appropriate metrics lead various researches and development under respective working groups category and know the right pathway to lead various researches and development under respective categories but the processes for newcomers and existing contributors may not be known that how to participate or take the right path to for respective workings.
As a result of this, the things within the CHAOSS community are not standardized. Therefore to know the right process and basic fundamentals of the work culture across the community, the goal of the community handbook is to centralize critical information and standardize parts of it across the CHAOSS project. The critical information and standardization parts majorly focus on the processes that CHAOSS uses so that CHAOSS have the agreement of how community accomplishes work, How newcomers can participate and follow the fundamentals of the community and what processes and pathway newcomers or existing members have to follow for availing the leadership within the CHAOSS community.
The handbook should serve as an instruction manual for existing and new community members on how to get work done in the CHAOSS project. This project involves a creative component of collecting and organizing content for the handbook as well as a technical component of defining how to represent the handbook.
WHAT IS THE NEED FOR IT?
Community Handbook is a document that defines the community’s key policies and procedures and outlines the community’s mission, values, and workings.
This handbook provides a clear introduction and workings to the newly joined members of the community. Currently, the CHAOSS community Handbook is available on the GitHub repository and needs to be revamped and refactored with more information for newcomers and existing community users. So this CHAOSS community-wide handbook will help newcomers and existing community members in the following ways:
- Formalizing and organizing CHAOSS community’s policies, having them all in one place
- Communicating the community’s Introduction, Mission, Vision, and leadership
- Understanding the CHAOSS community practices
- Contribution Guidelines
- Defining the Project Workflows
- Outlining the CHAOSS community Culture
- General FAQs
- Mentorship
PROJECT DESCRIPTION:
Community handbook will be divided into various “Sections” which will contain appropriate and detailed information for particular topics. The sections can be divided in the following ways:
- Introduction
- The CHAOSS Community way
- Path to Leadership
- Terminology
- Contribution Guidelines
- Developer
- Designer
- Writer
- Marketer
- Metrics
- CHAOSScon
- CHAOSScast
- Meeting Videos
- General FAQ
- Mentorship
- Google Summer of Code
- Outreachy
- Google Season of Docs
DETAILED PROJECT DELiVERABLES
1.) Introduction:
This section will act as the first page of the CHAOSS community handbook and will cover up the details, overview, and usage of the Handbook. Below are the following things:
A.) It will contain the Welcome message with a brief description of the CHAOSS Community which would help convince the readers to get through the Handbook. I will also include the Collage of Images taken from here https://chaoss.community/chaoss-photo-album/ which would highlight the various movements within the community. B.) The page will also contain the details about all the sections with one line description explaining every section and proper links. C.) Handbook Usage: Handbook Usage already exists here( shorturl.at/cqQU6 ) but I will revamp and refactor the existing Handbook usage with better markdown which will include Flow of the Handbook(I will include that how things happen when someone wants to add, remove or discuss things related to the handbook. It might follow up the process of communication way for any handbook related things.), Handbook Guidelines(which include its usage within the community and scope), Contribution to the handbook ( which includes that how one should use the repo in order to make changes, make PRs, Template to follow for making changes to the Handbook and Style Guide)and Sharing Feedback about Handbook. Within Sharing Feedback, I will include a template and different ways that users can follow up to provide or use GitLab issues for receiving it.
2.) The CHAOSS Community way:
The CHAOSS Community way will be important for people to understand the community practices and guidelines. Workflows would be able to make it more emphasized and outline the community practices in the best way. This section includes the following things:
A.) General Values: Outlining how Sustainability, Openness, and Transparency is handled within the CHAOSS Community. I will explain up these values that how the new users or existing users should understand it and take into consideration while working inside with the community. B.) Community Guidelines: This includes how actually one should get involved with the CHAOSS Community and follow basic terms. This will also explain the work culture followed inside the community. (Do’s and Don’ts). It will include the core contributor/maintainers checklist as well letting them others know that how should they work with maintainers and what are their checklist. C.) Working Groups: This page( https://chaoss.community/participate/ ) contains information about the Working Groups like Description of the WG, Repo link and Meeting information but within the handbook, I will include that how to participate in the different working groups and understand the process of evaluating the metrics, understanding the work culture for respective WG and how to become the core contributors for different working groups.
3.) Path to Leadership:
While gaining leadership in an open-source project can be vital to a community’s own success in the commercial world. So, taking that into consideration I will include the following:
A.) Technical Leadership: This will include the processes and responsibilities for Repo Maintainers, Documentation Writer and Website maintainer B.) Governance Leadership: this will include the pathways for Board member and Decision Maker C.) Operational Leaderships: This will contains the pathway for Community managers
4.) Terminology:
Terminology would help describe the terms and respective belongings that are used frequently within the CHAOSS community. Moreover, I will also include the Terminology usage guidelines like Capitalization, Abbreviations, and Words to Avoid with reasons. The Terms which will be included are CHAOSS Project, Open Source Community Health, Code Review, Working Group, Open Source Software Metric, Common Metric, Diversity, and Inclusion Metric, Evolution Working Group, Risk Working Group, Value Working Group, Metric Release, Focus Area.
5.) Contribution Guidelines:
This is the main context for any open source community since most open source community depends upon the contributions or volunteering working so this will help any newcomer/user joining the community to understand the basic necessity and guidelines they have to follow. So this will include the following details:
A.) Understanding the Roadmap of the Community: This topic will lead to an overview of the roadmap of the CHAOSS community which will help users know which way or process to follow giving priorities to the various workings within the CHAOSS Project. B.) Explaining the necessary things needed for making hands-on any contribution like development, Documentation, Designing, Testing, etc C.) Giving a brief overview of GitLab workings D.) Reviewers/Maintainers Guide
This section will also contain the “Roles and Responsibilities” for each Contribution category which are below:
a.) DESIGN: This subsection will include the “CHAOSS Design Work Flow” and the Design Guidelines which will contain Design Principles, Process and Tools Used which the contributors have to follow while making their contribution to the design field. b.) DEVELOPMENT: This will contain the guide for the contribution to the codebase. It will contain the Technical requirements, Project Structure, Project Setup(Augur, Cregit, GremoireLab) c.) DOCUMENTATION: This will Include Resources for Documentation including tools and Style Guide. d.) OUTREACH: This will include that how contributors can support the CHAOSS community in outreach growth- Writing Blogs, Using Social Handles, Organising meetups and events
6.) Metrics
Currently, the CHAOSS community website contains the information of Metric Releases( https://chaoss.community/metrics/ ) and it is more important for people to understand how to follow the process to make their metrics website available on that website. So this section will lead the information that will help users know the processes and working in order to have their own metric release.
7.) CHAOSScon:
The information about CHAOSScon already exists on GitHub( https://github.com/chaoss/governance/blob/master/community-handbook/chaosscon.md ) and Website( https://chaoss.community/CHAOSScon-2020-NA/ ) but it makes more sense adding the details and information explaining processes and managing ways for CHAOSScon in the Handbook. Within the Handbook it will contain the following Information:
A.) Details about Organising Committee: It will explain the processes of how to participate in the organizing committee of CHAOSScon B.) Management for Call for Proposal Process: This will include managing the author registration, submitting proposals and documentation, review, and approval process. C.) Managing and Publishing of the CHAOSScon program D.) How to manage Advertising and Marketing stuff E.) How to handle Sponsorship proposals and funds Including Packages
8.) CHAOSScast:
CHAOSScast information exists here https://github.com/chaoss/governance/blob/master/community-handbook/chaosscast.md and it will be included in Handbook with some additional details like Participation, Organising Committee, Advertising, and Marketing Materials.
9.) Meeting Videos:
This will contain all the meeting videos along with the description such as, Attendees, Agenda, etc that have happened in the past and available on Youtube.
10.) General FAQs:
These will contain the general common questions that are asked within the community and this will help newcomers and existing community members to answer some of them.
11.) Google Summer of Code:
This section will contain information about the Google Summer of Code, Eligibility Criteria, and information regarding how people can participate under the CHAOSS community in Google Summer of Code. This section will also contain the Proposal Template which people can use to draft their proposal and roles and responsibilities. Moreover, this will also contain the information that would help existing community members to learn the process of becoming org admin and mentors.
- Outreachy:
This section will contain information about the Outreachy, Eligibility Criteria, and information regarding how people can participate under the CHAOSS community in Outreachy.this will contain the roles and responsibilities including the process of becoming the org admin and mentors.
- Google Season of Docs:
This section will contain information about the GSoD, Eligibility Criteria, and information regarding how people can participate under the CHAOSS community in GSoD. This will contain the roles and responsibilities including the process of becoming the org admin and mentors.
PROJECT EXPECTED OUTCOME:
Handbooks play an important role in any community. Similarly, this CHAOSS community-wide handbook will result in having better organized and detailed documentation for the CHAOSS community. It would become easy for any newcomer who joins the community as well as existing members within the community to understand the fundamentals and workings of the CHAOSS community. Moreover, this handbook will result in having the various processes and paths to different work cultures within the CHAOSS community.
TECHNICAL DETAILS:
I propose to use the Gitbook platform for maintaining the handbook because it is a user-friendly, collaborative project for teams to work more effectively and efficiently. Some Features of the GitBook Platform:
- WYSIWYG: Powerful and yet beautiful text editor
- Markdown: Powerful and Productive support of markdowns shortcuts
- Rich Embed: Embeds external web content like videos, code snippets, articles, music, and more
- Dashboards for Writers: Have an intelligent dashboard for writers which supports visual editing
- Drafts: draft new changes and collaborate asynchronously
- Support Comments: Discuss and review draft changes
- Track Writing History: Track everything. Review and revert changes
- Insights: It also supports insights which track the traffic, rating, and content quality
- GitHub Sync: Keeping the workflow and keep syncing the docs with GitHub
- Customization Branding: Custom domains, custom logos, fonts, color, themes, header, etc
Here are the few images which give the glimpse of the platform
- shorturl.at/GNQR4
- shorturl.at/gATZ8
- shorturl.at/qrE57
- shorturl.at/rFRX6
- shorturl.at/eyLW1
- shorturl.at/rwHS8
-- Where will the Handbook be hosted?
The Handbook will be hosted on the GitBook itself where GitHub provides a proper mechanism for Custom Domain, Common Error, and SEO.
Custom Domains: If the CHAOSS community wants to host it on the custom domain then it will be shown up like this docs.chaoss.community The org is required just to build any subdomain they wish to have. To set up the Organisation domain, go to the organization’s settings on the Gitbook Platform. Image Example: shorturl.at/GNQR4
GitBook spaces are served over our own CDN with HTTPS enabled by default. The certs are issued by LetsEncrypt
Supportable Domains:
- Sub Domain: www.example.com
- Custom Domain: docs.example.com
-- How to sync the Gitbook with GitHub so that editing can be done on both the platforms effectively?
The integration with GitHub is very easy to use: if anyone changes some content on GitBook, their edits are pushed to a GitHub repository. Conversely, commits pushed to a GitHub repository are imported within the GitBook.
Setup the GitHub Integration:
- From your space within the GitBook platform, click on the integrations tab > GitHub
- Authorize GitBook to access your GitHub account linked with your organization
- Go to your org GitHub and make a repo for “HandBook” for eg. chaoss-handbook
- Now Select the repository named chaoss-handbook that you want to connect within the authorization option inside the GitBook platform.
Once these steps are completed, GitBook will add a webhook to the chaoss-handbook repository that will allow it to fetch content on every change to the repository. When making changes to GitBook, a new comment will be pushed.
That’s it! Anyone can continue editing from GitBook or GitHub repository.
-- How to edit pages on the GitBook platform?
Anyone who wants to edit anything within the GitBook platform is required to join the GitBook platform with an invite or join link. GitBook supports visual editing where users can write within the pages directly.
A draft is an editable version of user content that is only accessible by the writers and is automatically created once you start writing (first letter on the editor, creation of a new page, uploading a picture, etc.).
Changes made on a draft are proper to it which allows users to contribute on the same document with other members simultaneously without creating any conflicts! This is what we call asynchronous editing and conflict resolution.
The first version of the draft isn't always ready to be published straight away. Use ""save"" when you want to continue your work later, or if your content is not yet ready to be “merged"".
When you finish editing, you can ""merge"" your draft. The content you wrote or the changes you made will then be available for your team members and/or be public.
Image Examples: shorturl.at/gATZ8 and shorturl.at/qrE57
-- Content Structure:
Table of Contents: Each space can contain as many pages as you need to write your documentation. All these pages are visible on the left side of your screen in what we call the Table of Content. From the Table of Content you can manage your pages: create new pages, group of pages, add external links, add a variant, import external docs like websites or files that are Markdown (.md or .markdown), HTML (.html), Microsoft Word (.docx).
Initial Page: The initial page is the homepage or the root of your documentation and basically works as the master of all the pages of your documentation. Because it is the main entrance of your documentation and of your space, this page can't be moved, deleted, have children or be under a group.
Pages: A page has a title, an optional description on the top of the editor. You can then write and add any kind of content to it. You can nest pages by dragging and dropping a page below another. The children of a page will be hidden but can be collapsed.
External Links: These entries are external links and do not have any content in the editor. Their main function is to link to external websites.
Variants: You can create an alternative content to your documentation by creating a variant. This can be useful to document multiple versions of an API, a library, or translations.
Image Example: shorturl.at/eyLW1 and shorturl.at/rFRX6
-- How the Handbook will be presented on the client-side?
The Chaoss community handbook will be accessible with a subdomain which can be https://docs.chaoss.community and it will look in the following ways at user end:
- Mattermost Handbook - https://handbook.mattermost.com/
- Linux Foundation Community Bridge Docs - https://docs.linuxfoundation.org/docs/ And many more
PROJECT TIMELINE:
1.) Community Bonding Phase (17 Aug - 13 Sep)
A.) Week 1-4:
- Discuss the project with mentors
- Research and collect the information needed for the various sections within the project, ask clarifying questions to the community
- Clarify with the community what platform to use for the handbook (I suggest GitBook) and set that up
- Contribute to docs issues
2.) Doc Development Phase (14 Sep - 30 Nov)
A.) Week 5 (14 Sep - 20 Sep)
- Draft” Introduction Section
B.) Week 6 (21 Sep - 27 Sep)
- Draft “The CHAOSS Community Way” section
C.) Week 7 (28 Sep - 4 Oct)
- Draft the “Path to Leadership” Section
- Draft the “Terminology” section
D.) Week 8 (5 Oct - 11 Oct)
- Draft the Roadmap of the Community
- Draft design contribution guidelines
E.) Week 9 (12 Oct - 18 Oct)
- Draft Development section
F.) Week 10 (19 Oct - 25 Oct)
- Writing and Outreach section guidelines
G.) Week 11 (26 Oct - 1 Nov)
- Draft Metrics section
- Draft CHAOSScon section
H.) Week 12 (2 Nov - 8 Nov)
- Design the Meeting Section
Draft General FAQs of community
I.) Week 13 (9 Nov - 15 Nov)
Draft about GSoC Guidelines
J.) Week 14 (16 Nov - 22 Nov)
- Draft about Outreachy Guidelines
K.) Week 15 (23 Nov- 29 Nov)
- Buffer Time; Polishing and improving the whole docs
3.) Evaluation Phase (30 Nov - 5 Dec)
A.) Week 16:
- Draft a project report
- Fill up the evaluation for the project
COMMUNITY INTERACTIONS
1.) Involvement and Discussions with the community.
Well, I have been surfing around in the CHAOSS community since April 2020 and have been involved with various discussions with community members and with my specific project mentors( Georg Link and Armstrong Foundjem). One such discussion which aroused a greater interest of the community members was “Proposing Gitbook as a platform for hosting Community Handbook'' and can be found on the CHAOSS archive mailing list thread with the named as Proposing Gitbook as a platform for hosting Community Handbook. I have been also participating in the community weekly calls which helped me giving updates to the community.
2.) How will you collect the information required for this project?
Since this project requires setting up the community-wide handbook so the information that has to be accessed within it will be collected from and discussed with community members. As I have proposed my timeline above so according to that I will be able to discuss and collect the information needed during my community bonding period.
I will be researching on the various sections in accordance with CHAOSS and keep up the threads going on the mailing list. I will try asking clarifying questions from my mentors and the community depending upon the requirements.
In order to have concise discussions, I will also be joining weekly calls.
3.) How do you propose you will be keeping the community informed of your progress and any problems or questions you might have over the course of the project?
In order to have flexibility and transparency, I will try communicating over the mailing list discussion for asking my doubts.
I will be sharing my weekly progress as a blog post which will include the scrum documentation and challenges faced which will be shared on the community mailing list itself in order to reach the bigger audience inside the open-source organization.
I would also be attending weekly community calls in order to have proper suggestions and discussions over the main issues.
I’m also planning to create a Trello board with the available weekly tasks. The mentors can then use this board to get a clear and concise understanding of the current issues and features that are being worked.
4.) What will you do if you get stuck around with your project and your mentor isn’t around?
I believe that the mentor’s role is to guide the students in the right direction and not to explain every loops corner to the student. The research and implementation of the project are the sole responsibilities of the student. Keeping that in mind I will only try to get help from my mentor as a last resort.
However, if the mentor is not around/busy at the moment I need help, I will then move onto sharing the issue I’m having within the CHAOSS community. I am sure someone would be able to help me out with any challenges I come across. I will also share the issue on online forums/dev communities like dev.to
Moreover, I would try participating in any weekly calls for help within the CHAOSS community in order to ask my doubts.