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:
- boron
- Project name:
- Rework the documentation hosting & generation and Restructure getting started pages and developer guides.
- Project length:
- Standard length (3 months)
Project description
Abstract :
A documentation is designed to assist end users and developers to use a product or service. Good documentation is very important because it provides an avenue for users to learn how to use a software, its features, tips, tricks and also resolve common problems encountered when using the software. It also reduces support cost and is part of the corporate and open source identity of the product : a good documentation is a sign of healthiness of the product and the developer team.
Without a good documentation, a user may not know how to do the above things effectively and efficiently. Documentations can play a pivotal role in ensuring a product's success because great communication is and will always be at the heart of any business or product and a great documentation just takes that communication and puts it in a manageable framework that everyone can access for success.
Every documentation site needs a good building and hosting workflow pipeline, in an organization like AGL, with multiple versions and a lot of elaborative documentation, the documentation files (markdowns) are spread across multiple repositories, making the task of maintaining and updating them incredibly complex and time intensive.
Current State :
- AGL doc website is based on a collection of markdown files fetched from various repositories.
- The doc pages are currently hosted within the individual sources as markdown using the engine of the cordova project.
- This leads to a four repository setup for the documentation build and hosting process :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Contains the Jekyll website template.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Contains tools to automatically generate a technical website from Markdown files.
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Source (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) for general documents, guides.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Deployed GitHub pages repository for the documentation site [https://gist.github.com/growupboron/docs.automotivelinux.org].
- A tool (script) available in docs-tools [https://github.com/automotive-grade-linux/docs-tools] takes care of collecting and templating all markdown files according to the fetched_files.yml located in docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate].
- The current workflow of agl documentation website generation : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- The section_version.yml contains the links to all the book yaml files, it proceeds to fetch all book yaml files from remote repositories to the docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. The book yaml files contain all the url to your markdown files from the remote repository.
- As soon as all the markdown files are fetched, the tools process to generate the AGL doc website in the docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] which is correspondingly deployed.
- The current process of maintaining the pipeline is not user and developer friendly, especially to new contributors. This workflow pipeline (of building and hosting) can be simplified and streamlined way more for developers to focus on the documentation part rather than maintain documentation generation and deployment workflow.