このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Kolibri
- テクニカル ライター:
- StephDix
- プロジェクト名:
- Kolibri エコシステムのドキュメントのスタイルとワークフローの規則
- プロジェクトの長さ:
- 長期実行（5 か月）
プロジェクトの説明
概要
このドキュメントでは、Learning Equality が Kolibri エコシステム プロジェクトについて記録した情報に、スタイル ガイドラインとワークフロー管理を実装する方法について詳しく説明します。
概要
提案内容は 4 つのフェーズで構成されています。最初のフェーズでは、ソフトウェア開発における LE のコンセプトとスタイル ガイドに沿って、LE ドキュメント スタイル ガイドを完成させ、ユーザー補助のガイドライン、記述、形式に関する推奨事項を追加します。第 2 フェーズでは、ReadTheDocs と GoogleDocs のドキュメントに対して品質監査を行います。監査プランでは、チェックリストを使用してスタイル ガイドラインへの準拠を評価します。これらのチェックリストは、検出結果の記録とドキュメントへの変更の適用に役立ちます。3 つ目のフェーズでは、ReadTheDocs と Google ドキュメントのドキュメントのテンプレート構造、外観、操作性について作業します。今後の実装で再利用できるように、Google ドライブにテンプレートと画像のリポジトリを作成し、主要なドキュメント タイプの各テンプレート カテゴリを識別します。このタスクでは、プルリクエストのレビューで簡単に識別できるように、ドキュメントの問題を送信するためのテンプレートを作成します。最後に、協力者のガイドを作成します。このガイドでは、協力者のグループごとに役立つリソースをまとめ、情報へのアクセスを容易にします。
目的と範囲
この実装計画の目的は、Kolibri のドキュメントを使用するエンドユーザーのエクスペリエンスを向上させ、チームメンバーとコントリビューターがより優れたドキュメントを作成し、コミュニティで積極的にコラボレーションできるようにすることです。この実装は、ReadTheDocs と、Kolibri エコシステム内の Google ドキュメントのサブセットに適用されます。
オーディエンス
主な対象読者は、Kolibri ドキュメントの最も重要なユーザーである実装者、管理者、エンドユーザーです。Kolibri ドキュメントの作成と使用を目的とした、チームメンバーと共同作業者のセカンダリ オーディエンス。
目標
Kolibri エコシステムのドキュメントのスタイルガイドとワークフロー システムでは、ユーザーが次の要件を満たすことが求められます。わかりやすい言語と一貫したレイアウトで、読みやすいドキュメントを作成します。ドキュメント化された品質管理手法の維持を維持します。ドキュメント チャネル間で情報へのアクセスのしやすさを維持します。Kolibri オープンソース コミュニティでの共同イニシアチブを強化します。
データの提供元
情報源は、Kolibri、Kolibri Studio、Kolibri 開発 RTD ドキュメント、Google ドライブの Kolibri ツールキットです。
ウォームアップ アクティビティやプロジェクト固有のアクティビティを提供してくれた Radina Matic のおかげで、大きな助けになりました。組織が「ガイドライン」と「ガイド」と定義している内容や、コントリビューター向けのガイドの存在について、彼女からいただいたフィードバックは、アイデアを整理し、結論の下書きを作成するうえで役立ちました。
ソフトウェア
スタイルガイドの下書きは Google ドキュメントで作成します。このドキュメント プラットフォームは、公開する準備を整えながら反復処理を行うのに最適です。QA 監査では、Google フォームを使用してドキュメントを実施、評価します。スプレッドシートには、ドキュメント管理のためにフォームの回答が保存されます。 GitHub を使用して RTD ドキュメントをリファクタリングします。Git、Gitkraken、GitHub、Gitlab を使用したことがあります。Markdown と RestructuredText の基本的な知識がある。構文を学習するために、ドキュメントの修正に貢献する予定です。画像と GIF には Sharex を使用します。このツールは、さまざまな出力形式でレンダリングできる点が気に入っています。図の作成と画像の編集には Diagrams を使用します。図表ソフトウェアは、Google ドキュメント、Google ドライブ、LibreOffice とスムーズに統合されています。 ドキュメントの状況 調査フェーズでは、Kolibri のドキュメントのほとんどを改訂しました。プロジェクトのほとんどのドキュメントで、文法上の誤り、誤字脱字、レイアウト、タイポグラフィ、画像の使用における不整合、ドキュメントパスの混乱が見つかりました。たとえば、Kolibri のユーザーガイドでは、トラブルシューティングのセクションはトピックではなくサブトピックです。この情報は、エンドユーザーが目次からアクセスできるほど重要です。2 つ目の方法として、検索バーと目次ツリーを使用して他のトピックを開き、トラブルシューティング記事を探すこともできます。
[トラブルシューティング] セクションにアクセスするには、そのセクションを検索するか、[Kolibri を管理] を開いて、ドキュメントの一部としてトラブルシューティングがあることを確認する必要があります。ガイドとガイドラインの違い このプロジェクトの提案では、LE Kolibri ユーザー ドキュメント スタイルガイドと LE 翻訳ガイドラインの 2 つのドキュメントを分析しました。LE Kolibri ガイドでは、提案したトピックの概要とドキュメント計画から推奨事項とコメントを作成しました。また、ガイドの改善が必要な点についても記載しています。 LE 翻訳ガイドラインについては、スタイルガイドの推奨事項と既存の規則に基づいて形式とスタイルを変更しました。分析の際に特に気付いたことは、ガイドとガイドラインに分類されるドキュメントの間に存在する誤解です。
成果
提案とコメントに加えて、LE 翻訳ガイドの品質チェックを行いました。予備フォームについては、QA 監査タスクで詳しく説明します。評価で得られた最終的なコメントは次のとおりです。 ICU 構文 .js ウェブサイトの無効なリンク ガイドラインの作成に使用された形式に誤りがあります。 このドキュメントはガイドであり、ガイドラインではありません。一貫性のないタイポグラフィ。見出しやタイトルの不適切な使用、表現の不適切な使用、短縮形の不適切な使用。代替テキストの不適切な使用。繰り返しの多い文や指示。
両方のドキュメントの検出結果は、この提案の成果物の一部です。
プロジェクト固有のタスク
- LE ユーザー ドキュメント スタイルガイドの推奨事項（コメント）
- 新しいスタイルと形式の LE 翻訳ガイドライン。
- トピックの概要
- プロジェクトのタイムライン
- ドキュメント タスク