このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Linux Foundation
- テクニカル ライター:
- boron
- プロジェクト名:
- ドキュメントのホスティングと生成を再構築し、スタートガイド ページとデベロッパー ガイドを再構成。
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
概要 :
ドキュメントは、エンドユーザーとデベロッパーがプロダクトやサービスを使用できるように設計されています。優れたドキュメントは、ユーザーがソフトウェアの使用方法、機能、ヒント、コツを習得し、ソフトウェアの使用時に遭遇する一般的な問題を解決する方法を提供するため、非常に重要です。また、サポート費用を削減し、製品の企業およびオープンソースのアイデンティティの一部となります。優れたドキュメントは、製品とデベロッパー チームの健全性の証です。
適切なドキュメントがないと、ユーザーは上記の作業を効果的かつ効率的に行う方法を把握できない可能性があります。ドキュメントは、プロダクトを成功に導くうえで極めて重要な役割を果たします。優れたコミュニケーションは、あらゆるビジネスやプロダクトの中核をなすものであり、これからも常に存在し続けます。優れたドキュメントがあれば、そのコミュニケーションがわかりやすく管理可能な枠組みに組み込まれ、誰もが成功へと導きます。
すべてのドキュメント サイトには、優れたビルドとホスティング ワークフロー パイプラインが必要です。AGL のような組織では、複数のバージョンと多くの詳細なドキュメントがあり、ドキュメント ファイル（マークダウン）が複数のリポジトリに分散されているため、ドキュメントの維持と更新は非常に複雑で時間がかかります。
現在の状態 :
- AGL ドキュメント ウェブサイトは、さまざまなリポジトリから取得した Markdown ファイルのコレクションに基づいています。
- 現在、ドキュメント ページは、cordova プロジェクトのエンジンを使用して、個々のソース内でマークダウンとしてホストされています。
- これにより、ドキュメントの構築とホスティングのプロセスのために、次の 4 つのリポジトリが設定されます。
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Jekyll ウェブサイト テンプレートを含む。
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Markdown ファイルから技術ウェブサイトを自動生成するツールが含まれています。
- Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : 一般的なドキュメントやガイドのソース（マークダウン [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]）。
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : ドキュメント サイト [https://gist.github.com/growupboron/docs.automotivelinux.org] 用にデプロイされた GitHub Pages リポジトリ。
- docs-tools [https://github.com/automotive-grade-linux/docs-tools] で利用可能なツール（スクリプト）は、docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] にある fetched_files.yml に従って、すべてのマークダウン ファイルを収集してテンプレート化します。
- agl ドキュメント ウェブサイトの生成の現在のワークフロー : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- セクション_version.yml には、すべてのブック yaml ファイルへのリンクが含まれており、リモート リポジトリから docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] に、すべてのブック yaml ファイルを取得します。book yaml ファイルには、リモート リポジトリの Markdown ファイルへのすべての URL が含まれています。
- すべてのマークダウン ファイルが取得されるとすぐに、ツールが docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] に AGL ドキュメント ウェブサイトを生成します。このウェブサイトは、対応するデプロイ先にデプロイされます。
- 現在のパイプラインの維持プロセスは、ユーザーやデベロッパーにとって、特に新しいコントリビューターにとって使いやすくありません。このワークフロー パイプライン（ビルドとホストのパイプライン）は、デベロッパーがドキュメント生成とデプロイ ワークフローの維持ではなく、ドキュメント作成に集中できるように、さらに簡素化、効率化できます。