このページには、Google シーズンの 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 の使用方法を説明するリファレンス ドキュメントが必要です。
リファレンス ドキュメントには、以下を記載する必要があります。
- ランチャーのインターフェース: 各ウィンドウとタブの外観と機能
- グローバル設定とゲーム固有の設定の両方の説明
キーボード ショートカット/ホットキー
詳細オプション:
上級ユーザーは、ゲームの動作を微調整するために利用できるオプションについて、より技術的な追加情報を必要としています。
- ゲームメモ:
ユーザーが知っておくべきゲーム固有の情報(以下を含みます。ただしこれらに限定されません): - インストールの特徴 - 必要な追加ファイル - 通常とは異なるまたは異なるコントロール
- 既知の問題:
このセクションには、そのリリースに固有の既知のバグを記載します。
- リリースノート:
ドキュメントはバージョン管理されますが、リリースノート セクションを用意しておくと、最新リリースでの変更点の概要を説明するのに役立ちます。これには、新たにサポートされるゲームや新しいエンジンに関する情報など、現時点ではこのドキュメントの対象外である一部の領域が含まれる場合があります。
攻撃の計画:
まずは、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 日
- 未解決の項目をすべて完了し、ポータルを正式にリリースしてください。
- ポータルをリリースしたら、メンターに相談して、他の情報源から冗長な情報を削除します。