このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- ScummVM
- テクニカル ライター:
- カディ
- プロジェクト名:
- ドキュメント ポータルを起動する
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
調査目標:
- 異なるソースからの大量の情報を統合し、明確さ、一貫性、完全性のために情報を書き換えることで、バージョン管理された高品質なエンドユーザー ドキュメントを作成すること。
- ドキュメントは初心者でもわかりやすいものにする必要があります。テクノロジーに長けたユーザーを見下すのではなく、
- 静的サイト ジェネレータを使用してドキュメント ポータルを作成するには、
- 将来のオープンソースへの貢献のためにテンプレートと詳細な手順ガイドを作成し、将来を見据えたエンドユーザー ドキュメントを作成すること。
現状:
- 利用可能な ScummVM のドキュメントは、複数のソースにまたがっています。
- 情報は見つけにくく、重複することも多々あります。わかりにくいページでは、情報がわかりにくくなっています。
- どの情報が最新のもので、どれが古くなっているかを把握するのは困難です。
- 一部の情報が不足しているか不完全です。
問題の解決:
推奨されるドキュメントの構成:
ランディング ページ
|-- スタートガイド
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- （プラットフォーム）
|-- ScummVM の使用
| |-- ランチャー
| |-- 全般設定
| |-- ゲーム設定
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- 音楽とサウンド
|-- ヘルプ
|-- よくある質問
| |-- コンタクト
| |-- 既知の問題
| -- Reporting a bug
|-- Game Notes-- リリースノート
- ご利用方法:
多くの場合、新規ユーザーはクイック スタートガイドを探してすぐに利用を開始しています。プラットフォームによっては ScummVM のインストールが複雑になる場合がありますが、コンピュータへのインストールは複雑ではありません。
このクイックスタート ガイドでは、次の内容を取り上げています。
- Windows、Mac、Linux に ScummVM をインストールする方法
ゲームを読み込んで追加し、起動する方法。
ScummVM のインストール:
インストールが直感的でない場合や、ユーザーの技術的基盤が十分ではない場合、ユーザーにはサポートされているプラットフォームに ScummVM をインストールするための包括的なガイドが必要です。
それぞれの包括的なインストール ページには、以下の項目を含めます。
- システム要件と前提条件
- 適切なバージョンの ScummVM をダウンロードする方法
- ScummVM のインストール方法
- 選択したプラットフォームにゲームを読み込む方法（特に、ゲームの設計時にプラットフォームではないもの）
ScummVM の起動方法、ゲームの追加方法、ゲームの起動方法
ScummVM の使用:
ユーザーには、ScummVM の使用方法を説明するリファレンス ドキュメントが必要です。
リファレンス ドキュメントには、以下を含める必要があります。
- ランチャーのインターフェース。各ウィンドウとタブの外観と機能。
- グローバル設定とゲーム固有の設定の両方の説明
キーボード ショートカット/ホットキー
詳細オプション:
上級ユーザーは、ゲームの動作を調整するために利用できるオプションに関する、より技術的な追加情報を必要としています。
- ゲームメモ:
ユーザーが知っておく必要があるゲーム固有の情報（以下を含みます。ただしこれらに限定されません）: - インストールの特徴 - 必要な追加ファイル - 一般的または異なるコントロール
- 既知の問題:
このセクションには、そのリリースに固有の既知のバグを記載してください。
- リリースノート:
Google のドキュメントはバージョン管理されますが、リリースノート セクションがあると、最新リリースでの変更点の概要を説明するのに役立つ場合があります。これには、新たにサポートされるゲームや新しいエンジンに関する情報など、現時点ではこのドキュメントの対象外である内容が含まれる場合があります。
攻撃計画:
まずは、ScummVM のインストール ページのテンプレートを作成することをおすすめします。そうすれば、ポートの管理者/デベロッパーから必要な情報を最も簡単に取得できるからです（特にこの情報が薄いか存在しない場合）。既存のドキュメントからすでに手元にある情報を事前入力し、情報の完全性、正確性、通貨をチェックしたり、必要に応じて情報を追加したりします。
次に、既存のドキュメント（README、Wiki、ウェブサイト）を精査します。その後、必要に応じて各セクションに書き直して追加し、すべての情報を新しいポータルに取り込みます。また、ポータルが稼働した後、二重アップ、矛盾、その他の異常が発生しないよう、どのような情報がどこから取得されるかについてもメモします。
不足している情報がある場合は、メンター、デベロッパー、ポート メンテナンス担当者、その他の対象分野のエキスパートに相談し、各ページが可能な限り最新かつ包括的であるようにして、不足している情報を確認します。
メンターの承認を得て、共同作業の精神で、執筆プロセス全体を通して ScummVM コミュニティが開発中のポータルにアクセスできるようにし、リアルタイムのフィードバックを受け取り、途中で見落としがないことを確実にします。
Google デベロッパー向けドキュメントのスタイルガイドなどのスタイルガイドを使用して、一連の作業と今後のすべてのドキュメントの一貫性を確保することをおすすめします。
可能な場合はスクリーンショット、GIF、その他の視覚的資料を使用して理解を強化します。
スケジュール案:
コミュニティの絆 2020 年 8 月 17 日～ 9 月 13 日
メンターや幅広い ScummVM コミュニティと継続的に時間をかけて、プロジェクトのビジョンを微調整し、ドキュメントの構成や内容などの詳細を完成させます。
第 1 週 9 月 14 日～ 9 月 20 日
- プラットフォーム固有のインストール ページのテンプレートを作成します。
- テンプレートに既存の情報を事前に入力し、適切なポートの管理者/デベロッパーに配布して詳細を確認します。
第 2 週 9 月 21 日～ 9 月 27 日
- 新しいドキュメント ポータルを設定します。
第 3 週 9 月 28 日～ 10 月 4 日
ScummVM を使用する場合: - インターフェース - 全般設定 ScummVM のインストール: - 完成したテンプレートとして、プラットフォーム固有のインストール ガイドが返却されます。
第 4 週 10 月 5 日～ 10 月 11 日
ScummVM の使用: - ゲーム設定 - キーボード ショートカット ScummVM のインストール: - 記入済みのテンプレートはプラットフォーム固有のインストール ガイドが返却されます
第 5 週 10 月 12 日～ 10 月 18 日
詳細オプション: - クラウドと LAN - コントロール マッピング ScummVM のインストール: - 記入済みのテンプレートはプラットフォーム固有のインストール ガイドが返却されます
第 6 週 10 月 19 日～ 10 月 25 日
詳細オプション: - 構成 - コマンドライン オプション ScummVM のインストール: - 完成したテンプレートが返却されるプラットフォーム固有のインストール ガイド
第 7 週 10 月 26 日～ 11 月 1 日
詳細オプション: - グラフィック - オーディオ ScummVM のインストール: - 記入したテンプレートが返却されるプラットフォーム固有のインストール ガイド
第 8 週 11 月 2 日～ 11 月 8 日
ヘルプ: - よくある質問 - コンタクト - 既知の問題
ScummVM のインストール: - プラットフォーム固有のインストール ガイド（記入済みのテンプレートが返却されます）
第 9 週 11 月 9 日～ 11 月 15 日
ヘルプ: - バグを報告する - ゲームメモ - リリースノート
ScummVM のインストール: - まだ完了していないプラットフォーム ガイドを完了します。
第 10 週 11 月 16 日～ 11 月 22 日
- ポータル関連の決定事項（サイドバーのナビゲーション、テーマや CSS の調整など）の最終編集、校正、最終処理を行う
- すべてのリンクが想定どおりに機能することを確認します。
- 画像/GIF が正しく表示されることを確認します。
第 11 週 11 月 23 日～ 11 月 30 日
- 未解決のアイテムをすべて完了し、ポータルを正式に立ち上げます。
- ポータルがリリースされたら、メンターと相談して他の情報源から冗長な情報を削除します。