このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Kolibri
- テクニカル ライター:
- StephDix
- プロジェクト名:
- Kolibri エコシステムのドキュメント スタイルとワークフローの規則
- プロジェクトの期間:
- 長時間（5 か月）
プロジェクトの説明
抽象化
このドキュメントでは、Kolibri エコシステム プロジェクトにおける Learning Equality の文書化された情報に対するスタイル ガイドラインとワークフロー管理の実装について詳しく説明します。
概要
この提案は 4 つのフェーズから構成されます。最初のフェーズでは、ソフトウェア開発における LE のコンセプトとスタイル ガイドラインに沿ったユーザー補助ガイドライン、文章、形式の推奨事項を含む LE ドキュメント スタイルガイドを完成させます。フェーズ 2 では、ReadTheDocs と GoogleDocs のドキュメントに対して品質監査を実施します。監査計画には、スタイル ガイドラインの遵守を評価するためのチェックリストの利用が統合されています。このチェックリストは、調査結果を記録し、ドキュメントに変更を適用する際に役立ちます。フェーズ 3 では、ReadTheDocs と GoogleDocs ドキュメントのテンプレートの構造やデザインを担当します。Google ドライブにテンプレートと画像のリポジトリを作成し、今後の実装で再利用できるよう、主要なドキュメント タイプの各テンプレート カテゴリを特定します。このタスクを補完するテンプレートを作成して、pull リクエストの審査でドキュメントの問題を簡単に特定できるようにします。 最後に、コントリビューター グループごとに有用なリソースをグループ化したコントリビューター ガイドを作成します。これにより、情報へのアクセスの利便性を高めることができます。
目的と範囲
この実装計画の意図は、Kolibri のドキュメントを使用するエンドユーザーのエクスペリエンスを向上させ、チームメンバーとコントリビューターがより良いドキュメントを作成し、コミュニティ内で積極的なコラボレーションができるように支援することです。 この実装は、ReadTheDocs と、Kolibri エコシステムの Google ドキュメント ドキュメントのサブセットに適用されます。
対象
Kolibri ドキュメントの最も重要な利用者である実装者、管理者、エンドユーザーを主な対象者。Kolibri ドキュメントの作成と使用に関するチームメンバーと共同編集者の二次的な対象者。
目標
Kolibri エコシステム ドキュメントのスタイルガイドとワークフロー システムでは、ユーザーに次のことを想定しています。 わかりやすい言語を使用して、一貫したレイアウトでわかりやすいドキュメントを作成する。 文書化の品質方針が維持されます。ドキュメント チャネル間の情報へのアクセスのしやすさを維持します。Kolibri オープンソース コミュニティでの共同作業を強化します。
データの提供元
情報源は、Kolibri、Kolibri Studio、Kolibri 開発 RTD ドキュメント、Google ドライブの Kolibri Toolkit でした。
ウォームアップ アクティビティとプロジェクト固有のアクティビティを行ううえで、Radina Matic さんは大いに役立ちました。彼女が「ガイドライン」と「ガイド」として概念化している内容と、貢献者向けガイドの存在に関する意見をくれたおかげで、アイデアを整理し、結論を出すのに役立ちました。
ソフトウェア
Google ドキュメントでスタイルガイドの下書きを作成します。このドキュメント プラットフォームは、公開の準備が整うまで繰り返すのに最適です。QA 監査では、Google フォームを使用してドキュメントを実施、評価します。スプレッドシートには、ドキュメント管理のためにフォームの回答が保存されます。 GitHub を使用して RTD ドキュメントをリファクタリングします。Git、Gitkraken、GitHub、GitLab を使用してきました。Markdown といくつかの RestructuredText に関する実用的な知識があります。今後も構文の学習を続けるために、ドキュメントの修正に貢献する予定です。 画像と GIF には Sharex を使用します。このツールはさまざまな出力形式でレンダリングできる点が気に入っています。図表作成と画像編集には Diagrams を使用します。ダイアグラム ソフトウェアは、GoogleDocs、Google ドライブ、LibreOffice と美しく統合されています。ドキュメントの状態 検討段階では、Kolibri のドキュメントの大部分を改訂しました。文法的な誤り、入力ミス、レイアウト、タイポグラフィ、画像の使用方法の不整合に加え、プロジェクトのほとんどのドキュメントに、紛らわしいドキュメント パスがあることがわかりました。たとえば、Kolibri のユーザーガイドでは、トラブルシューティングのセクションがトピックではなくサブトピックです。この情報は、エンドユーザーが目次からアクセスするのには十分重要なものです。別の方法として、検索バーと目次ツリーを使用して他のトピックを開き、トラブルシューティングに関する記事を探すこともできます。
[トラブルシューティング] セクションにアクセスするには、トラブルシューティングを検索するか、[Kolibri を管理] を展開して、トラブルシューティングがドキュメントに含まれていることを確認します。 ガイドとガイドライン このプロジェクト提案では、「LE Kolibri User Documentation Style Guide」と「LE Translation Guidelines」の 2 つのドキュメントを分析しました。LE Kolibri ガイドには、提案したトピックの概要とドキュメント計画のほか、ガイドに改善が必要な点をいくつか記載し、推奨事項やコメントを記入しました。LE 翻訳ガイドラインについては、スタイルガイドの推奨事項と既存の規則に基づいて、形式とスタイルを変更しました。分析中に私が最も注意を引いたのは、ガイドとガイドラインに分類されるドキュメントの間に存在する誤解でした。
成果
LE 翻訳ガイドに対して品質チェックを行ったほか、QA 監査タスクで詳しく説明する予備フォームでの提案やコメントも行いました。 評価から得られた最終的なコメントは次のとおりです。 ICU Syntax .js ウェブサイトの無効なリンク このガイドラインの作成に使用されている形式が正しくありません。 このドキュメントはガイドであり、ガイドラインではありません。タイポグラフィに一貫性がない。 見出しとタイトルの不適切な使用、 不適切な言葉遣い、短縮形の不適切な使用。代替テキストの不適切な使用。 文言/ 指示の繰り返し。
両方のドキュメントで得られた調査結果は、この提案の成果物の一部です。
プロジェクト固有のタスク
- LE ユーザー ドキュメント スタイルガイドの推奨事項（コメント）
- 新しいスタイルと形式の LE 翻訳ガイドライン。
- トピックの概要
- プロジェクトのタイムライン
- ドキュメントのタスク