ScummVM プロジェクト

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

オープンソース組織:
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 日

  • 残りの項目を確定させ、ポータルを正式にリリースします。
  • ポータルがリリースされたら、メンターと相談して、他のソースから重複する情報を削除します。