This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- moja global
- Technical writer:
- Tlazypanda
- Project name:
- Documentation of Technical Onboarding Guide for FLINT
- Project length:
- Standard length (3 months)
Project description
Documentation of Technical Onboarding Guide for FLINT for guiding the new contributors through a technical onboarding so that new contributors can easily get started with minimum support from the maintainers.
Project Issues
The following is a list of the most crucial issues related to the current documentation: - Disorganized pieces of local setup guide instructions thus making it difficult for a new contributor to get started. - Multiple repositories of FLINT lack documentation of their purpose and are not linked to each other making it difficult for the newcomer to identify which repository is to be installed. - Windows installation is well documented but Linux based installation documentation has room for improvement. - Git workflow is not currently a part of the documentation
Proposed Solution
This proposal presents a solution for guiding the new contributors through a technical onboarding so that new contributors can easily get started with minimum support from the maintainers. This can be achieved by refactoring the current documentation to make it beginner friendly and also maintain a central standalone repository for all the documentation available. The project is divided into three phases:- - Review existing documentation and refactoring: The goal of this phase is to review the current guide and refactor it in a way that makes it concise and easily comprehensible by new contributors. The documentation also needs to be modified in order to make it more beginner-friendly by adding badges, emojis and information on issues labeled with first-timers-only or good first issue tags. - Create a central standalone documentation repository: The goal of this phase is to link all the documentation available in a logical sequential order at a standalone repository. This involves ordering the contribution guidelines, project setup instructions and step-by-step guides. - Add Developer workflow and community website for new developers: The goal of this phase is to add the Developer workflow which contains the git contribution guidelines and the tech architecture of the project along with the testing and QA guidelines. The Proposed community website will be a single page application displaying the workflow, first-timers issues that can be claimed by the new contributors and a list of all contributors. Phase 1: Review existing documentation and refactoring:
Modify the current documentation of the following repositories: - FLINT: The current documentation is not very detailed and does not provide a sequential order of prerequisite libraries required. The step-by-step instruction guides are divided into different pdfs but can be unified at a single place in a more concise manner. Also, the installation guides are catered to windows but for Linux installation redirecting to the FLINT.docker repository might be beneficial. - FLINT.docker: The current documentation doesn’t provide the purpose behind setting this repository which is to provide the Linux installation of FLINT through docker. The support through docker is only limited to Ubuntu 18.04 (Bionic Beaver) but can be extended to other Linux based distributions. The current documentation also needs to put an emphasis on the sequential manner of setting up the dockerfiles and also enough information about how to build from the makefile. - FLINT.example: The current documentation doesn’t provide the purpose behind setting this repository which is to provide an example of how to use the FLINT. The different sample runs can be better segregated with specific instructions for them to run. We also need to link this repository to our main FLINT repository providing users a way to navigate here in order to check out the example in action.
The following information needs to be added to the current documentation: - Git and GitHub use: This will include step-by-step instructions on how to fork, clone and then set the remote upstream for the repository. It will also provide information on how to rebase against the latest master and handle merge conflicts. - Badges & Emojis: The current documentation lacks Badges and Emojis which can help new contributors feel welcomed and find the issues less daunting. - Information about the First Timers/Beginner Friendly issues: This will help to redirect the new contributors to beginner-friendly issues and the community website. - Information about the Import-me repository: The Import-me repository acts as a baseline template for jump-starting any Moja Global repository. The current documentation fails to mention the importance for the same. It needs to be updated to mention the Import-me repository and the steps to choose this as a template on creating a new repository also needs to be added. There should also be an established process for coders to suggest additional features for the Import-me repository.
Phase 2: Create a central standalone documentation repository :
Tool to be used for hosting platform:
The proposed tools for this hosting platform is Read The Docs due to the following reasons:- - Ranked highly among different hosting platforms. - Automatic updation on pushing commit - Easy to set up and troubleshooting support available easily due to the large community using it - Documentation is formatted using reStructuredText and the output is compiled by Sphinx.
Organize all content in a logical sequential manner:
The proposed order of content is as follows:- - Introduction to developer documentation: This section will cover an introduction to Moja Global and FLINT. - Contributing: This section will consist of subsections “Ways to Contribute” (in terms of code/reporting bugs/translation/documentation/organizing events etc.) and “Code Of Conduct”. - Development Setup: This section will consist of subsections “Git & GitHub Workflow”, “Windows Installation”, “Linux Installation”. - Developer Workflow: This section will consist of discussion on the tools integrated for testing and how to perform manual testing on your pull request and more as documented in the next phase. - Join us: This section will provide the various social forums such as Slack channels in order to connect and work with Moja Global.
Phase 3: Add developer workflow and community website for new contributors:
Developer Workflow Documentation:
The developer workflow documentation will consist of the following subsections:
- Tech Stack/Architecture used and the various modules in the code: Documentation to familiarize the new contributors with the Tech stack implemented, the various libraries and modules of the codebase.
- The integrated testing and coverage tools: Introducing new contributors to the CI/CD pipeline tools used for testing, Coverage bots and Automated Quality Checks run against their code. Also providing them guidelines on who to approach if the tests fail.
- Bots used to ease the workflow e.g - Zulipbot: Designing content templates for the bots to be displayed and Documentation to be available to allow users to understand the bots and even improve upon the bot’s configuration by contributing.
- Manually testing and submission of a pull request: Documentation to be provided on how to manually test Pull requests against certain standards and upload results in terms of screenshots/gifs on submission of Pull Requests.
- Pull request review guidelines to be followed by contributors: Guidelines on tagging certain teams for review and adding labels such as “needs review” to the pull request to allow for the maintainers to respond back.
Community Website:
The community website will have the following features:-
- Information about our Workflow: The workflow will consist of the series of actions a new contributor can begin with i.e - claiming a first timers issue, followed by creating a first timers issue for someone else and helping others by providing feedback and reviewing their pull requests.
- List of First timer only issues: The list of issues specifically meant for first-timers or new contributors.
- List of Stale issues: The list of issues which haven’t been worked on for a long period of time and hence are available to be picked by contributors.
- List of Contributors: The list of contributors who have so far contributed to Moja Global repositories.
- Recent Contributors: The list of contributors who have recently contributed to Moja Global repositories.
- Links to join chat forums: Information and links to join the Slack community to resolve their queries and have further discussions on the projects.