このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソース組織:
- Linux Foundation
- テクニカル ライター:
- boron
- プロジェクト名:
- ドキュメントのホスティングと生成を再構築し、スタートガイドのページとデベロッパー ガイドを再構成します。
- プロジェクトの期間:
- 標準期間（3 か月）
プロジェクトの説明
概要 :
ドキュメントは、エンドユーザーとデベロッパーがプロダクトやサービスを使用する際に役立つように設計されています。優れたドキュメントは、ユーザーがソフトウェアの使い方、機能、ヒント、コツを学び、ソフトウェアの使用時に発生する一般的な問題を解決するための手段となるため、非常に重要です。また、サポート費用も削減できます。優れたドキュメントは、製品とデベロッパー チームの健全性を示すものであり、製品の企業およびオープンソースのアイデンティティの一部でもあります。
適切なドキュメントがないと、ユーザーは上記を効果的かつ効率的に行う方法がわからない可能性があります。優れたコミュニケーションは、あらゆるビジネスやプロダクトの中心に常に存在します。優れたドキュメントは、そのコミュニケーションを誰もがアクセスできる管理可能なフレームワークに落とし込み、プロダクトの成功を確実にするうえで重要な役割を果たします。
すべてのドキュメント サイトには、優れたビルドとホスティングのワークフロー パイプラインが必要です。AGL のような組織では、複数のバージョンと多くの詳細なドキュメントがあり、ドキュメント ファイル（マークダウン）が複数のリポジトリに分散しているため、ドキュメント ファイルの保守と更新のタスクが非常に複雑で時間がかかります。
現在の状態 :
- AGL ドキュメント ウェブサイトは、さまざまなリポジトリから取得されたマークダウン ファイルのコレクションに基づいています。
- 現在、ドキュメント ページは、cordova プロジェクトのエンジンを使用して、個々のソース内に Markdown としてホストされています。
- これにより、ドキュメントのビルドとホスティングのプロセス用に 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 ページ リポジトリをデプロイしました。
- 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]
- section_version.yml にはすべてのブックの YAML ファイルへのリンクが含まれています。このファイルは、リモート リポジトリから docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] にすべてのブックの YAML ファイルをフェッチします。ブックの YAML ファイルには、リモート リポジトリの Markdown ファイルへのすべての URL が含まれています。
- すべてのマークダウン ファイルが取得されるとすぐに、ツールが処理されて、対応する docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] に AGL ドキュメント ウェブサイトが生成され、デプロイされます。
- 現在のパイプラインの維持プロセスは、特に新規のコントリビューターにとって、ユーザーやデベロッパーにとって使いやすいものではありません。このワークフロー パイプライン（ビルドとホスティング）を大幅に簡素化して効率化することで、デベロッパーはドキュメントの生成とデプロイのワークフローの維持ではなく、ドキュメントの作成に集中できます。