The Linux Foundation project
Stay organized with collections
Save and categorize content based on your preferences.
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThis Google Season of Docs project focuses on enhancing the Automotive Grade Linux (AGL) documentation by improving its hosting, generation process, and overall structure.\u003c/p\u003e\n"],["\u003cp\u003eThe current AGL documentation setup involves a complex, four-repository system that makes maintenance and updates difficult for contributors.\u003c/p\u003e\n"],["\u003cp\u003eThe project aims to simplify this workflow, enabling developers to concentrate on content creation rather than managing infrastructure.\u003c/p\u003e\n"],["\u003cp\u003eBy streamlining the documentation process, the project seeks to improve accessibility and usability for both end-users and developers.\u003c/p\u003e\n"],["\u003cp\u003eThis initiative will ultimately benefit the AGL ecosystem by providing a more efficient and user-friendly documentation experience.\u003c/p\u003e\n"]]],["The Linux Foundation's Google Season of Docs project, led by technical writer boron, aims to revamp AGL's documentation. The project will rework documentation hosting and generation, and restructure getting started pages and developer guides. AGL's current documentation process involves fetching markdown files from multiple repositories, using tools from `docs-tools` to build the site, and then deploying it to `docs-gh-pages`. The current pipeline is complex and not developer-friendly, thus requiring a more streamlined workflow for developers to focus on the documentation.\n"],null,["# The Linux Foundation project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\n### Project summary\n\nOpen source organization:\n: The Linux Foundation\n\nTechnical writer:\n: boron\n\nProject name:\n: Rework the documentation hosting \\& generation and Restructure getting started pages and developer guides.\n\nProject length:\n: Standard length (3 months)\n\n### Project description\n\n#### Abstract :\n\nA 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.\n\nWithout 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.\n\nEvery 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.\n\n#### Current State :\n\n- AGL doc website is based on a collection of markdown files fetched from various repositories.\n- The doc pages are currently hosted within the individual sources as markdown using the engine of the cordova project.\n- This leads to a four repository setup for the documentation build and hosting process :\n- Docs-webtemplate \\[https://github.com/automotive-grade-linux/docs-webtemplate\\] : Contains the Jekyll website template.\n- Docs-tools \\[https://github.com/automotive-grade-linux/docs-tools\\] : Contains tools to automatically generate a technical website from Markdown files.\n- 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.\n- 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\\].\n- 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\\].\n- The current workflow of agl documentation website generation : current_workflow \\[https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing\\]\n- 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.\n- 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.\n- 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."]]