このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Open Collective
- テクニカル ライター:
- Anna e só
- プロジェクト名:
- 一般的なヘルプ ドキュメントを改善
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
第一印象 同じ章の他のセクションに詳細なエントリがあるのに、説明ページに補足メディア（動画、GIF、画像）がないことはよくあります。たとえば、[コレクションを編集する] は手順のみで構成されていますが、[財務ホストを追加する] には補足メディアが組み込まれています。
閲覧したページでは、alt テキスト属性を使用してメディアが説明されていません。画像の説明がないと、スクリーン リーダーを使用するユーザーや、メディアが読み込まれない可能性がある低速なインターネット接続を使用しているユーザーは、ドキュメントを完全に理解することができません。
ドキュメントの一部のセクションでは、会計ホストを変更するなど、よくある質問とユーザー インターフェースの操作手順が統合されています。ドキュメント インターフェースには目次がないため、登録レコードの変更による影響を意識して客観的な説明を求めるユーザーは、ドキュメントが冗長で正直すぎると捉える可能性があります。
技術ドキュメントの言語はかなり一貫していますが、一般公開されているスタイルガイドのドキュメントでは、どのようにドキュメントを作成すべきかについてはあまり詳しくありません。[Contributing] ページには技術ドキュメントへの貢献が記載されているため、Open Collective とコントリビューター候補の双方にとって、より包括的なガイドラインが役立つでしょう。
提案 ユーザーヘルプページの見直しと、現在の構成と見直しをご提案します。
方法とタイムライン コミュニティと協力して、さまざまな期間で継続的にフィードバックするサイクルを促進することで、Open Collective のドキュメントを改善したいと思います。
コミュニティの絆を深める期間（2019 年 8 月 1 日～ 9 月 1 日）: Open Collective コミュニティについて知る注目を集めているプロジェクトや開始したばかりのプロジェクトのアクティブなメンバーにインタビューし、ドキュメントの現在の状態について質問する（報告 1）。問い合わせと問題を追跡するために使用したすべての内部システムと、それらを Open Collective ドキュメント（レポート #2）に文書化するプロセスをメモします。現行バージョンのドキュメントの潜在的な問題を評価し、その解決計画を作成する（レポート #3）。
9 月 2 ～ 6 日: 最初のフィードバックと調整サイクル。コミュニティの結束期間中にコミュニティから寄せられたすべてのコメントと提案を踏まえて行います。計画はうまくいったか？何か変更すべき点はありますか？（報告 4）
9 月 9 ～ 20 日: ドキュメントのコンテンツが少ない章を使用した概念実証の開発。公開スタイルガイドのドラフト（レポート #5）。
9 月 23 ～ 25 日: 評価のための概念実証の提出（クローズド グループ）。
9 月 26 ～ 27 日: 概念実証を公開する前に調整が必要な点はありますか？時間が必要な場合必要に応じて調整してください。（報告 6）
9 月 30 日～ 10 月 9 日: 概念実証を公開。2 回目のフィードバック サイクル（公開グループ）。
10 月 10 ～ 15 日: 最終的な概念実証の評価と調整サイクル。（レポート #7）
10 月 16 ～ 20 日: 活動を少し休む [1]。
10 月 21 日～ 11 月 23 日: 公開スタイルガイドが確定しました（レポート 8）。スタイルガイドに記載されているすべての指示を、すべてのユーザー向けドキュメント ページに適用する（報告 #9）。実施されたすべてのアクティビティを評価し、コミュニティへのさらなる推奨事項をまとめたレポート（レポート 10）。
プロジェクトの期間は、リクエストに応じて延長できます。
[1]: ドキュメンタリー シーズンの申請前に計画された旅行。
成果物 - 実施されたアクティビティに関する公開レポート 10 件 - Open Collective と外部コントリビューターの両方が使用できる公開スタイルガイド - ユーザー ドキュメント ページの刷新