このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Linux Foundation
- テクニカル ライター:
- ホウ素
- プロジェクト名:
- ドキュメントのホスティングと生成、再構成のスタートガイド ページとデベロッパー ガイドを手直ししました。
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
要約 :
ドキュメントは、エンドユーザーやデベロッパーがプロダクトやサービスを使用する際に役立つように設計されています。優れたドキュメントは、ソフトウェアの使い方や機能、ヒント、コツを学び、ソフトウェアを使用する際に発生する一般的な問題の解決方法をユーザーに教える手段になるため、非常に重要です。また、サポート費用も削減でき、プロダクトの企業 ID やオープンソース ID の一端を担います。優れたドキュメントは、プロダクトとデベロッパー チームの健全性の証となります。
適切なドキュメントがなければ、ユーザーは上記のことを効果的かつ効率的に行う方法がわからない可能性があります。ドキュメントは、プロダクトを成功に導くうえで極めて重要な役割を果たします。優れたコミュニケーションは、あらゆるビジネスやプロダクトの中心であり、これからもそうであるからです。優れたドキュメントは、コミュニケーションを取り、誰もがアクセスできる管理しやすいフレームワークにまとめます。
すべてのドキュメント サイトには、構築とホスティングを行う優れたワークフロー パイプラインが必要です。AGL のような組織では、複数のバージョンと多数の詳細なドキュメントがあり、ドキュメント ファイル（マークダウン）が複数のリポジトリに分散しているため、メンテナンスと更新のタスクが非常に複雑で時間がかかります。
現状 :
- AGL ドキュメント ウェブサイトは、さまざまなリポジトリから取得したマークダウン ファイルのコレクションに基づいています。
- ドキュメント ページは現在、Cordova プロジェクトのエンジンを使用して、個々のソース内でマークダウンとしてホストされています。
- これにより、ドキュメントの作成とホスティング プロセス用に 4 つのリポジトリが設定されます。
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Jekyll のウェブサイト テンプレートが含まれています。
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : マークダウン ファイルから技術ウェブサイトを自動生成するツールが含まれています。
- 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]
- セクション_version.yml にはすべての book yaml ファイルへのリンクが含まれており、リモート リポジトリから docs-webtemplate にすべての book yaml ファイルを取得します [https://github.com/automotive-grade-linux/docs-webtemplate]。書籍の yaml ファイルには、リモート リポジトリのマークダウン ファイルへの URL がすべて含まれています。
- すべてのマークダウン ファイルがフェッチされるとすぐに、対応するデプロイされる docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] に、ツールによって AGL ドキュメント ウェブサイトが生成されます。
- パイプラインのメンテナンスに関する現在のプロセスは、特に新しいコントリビューターにとって、ユーザーやデベロッパーにとって使いやすいものではありません。（ビルドとホスティングの）このワークフロー パイプラインは簡素化、合理化されて、開発者はドキュメントの生成とデプロイのワークフローではなく、ドキュメントの部分に集中できるようになります。