ソースコード製品に寄せられるサポートチケットの大半は、バグではありません。インストールの問題、設定に関する質問、そして「Xを変更するにはどうすればいいか」という依頼であり、要所に置かれた数ページがあれば答えられたはずのものです。優れた顧客向けソフトウェアドキュメントは、こうした質問を軸に構成されています。つまり、購入者がアプリをインストールし、設定し、使い、カスタマイズし、アップグレードし、問題が起きたときに解決するために何が必要か、ということです。
ドキュメントは、そもそも購入してもらえるかどうかにも影響します。WebアプリやSaaSのソースコードを販売する方法のガイドで紹介している信頼のシグナルのひとつであり、AppTrovoの審査担当者は、製品を掲載する前に明確なインストール手順と使用方法があるかを確認します。このガイドでは、何をどの順番で書けばよいのか、そしてほとんど手間をかけずに内容を正確に保つ方法を説明します。
目標はページ数を増やすことではありません。1件の販売あたりのチケット数を減らすことであり、それこそが買い切りライセンスを長期的に利益の出るものにします。
コード製品にはどのドキュメントが必要か
ソースコードの購入者は、それぞれ異なる目的を持ち、異なるタイミングでやって来ます。読者がすぐに答えを見つけられるよう、ドキュメントを目的別に分けましょう。Diátaxisフレームワークは、チュートリアル、ハウツーガイド、リファレンス、解説という分け方でよく知られたモデルです。販売用のWebアプリであれば、次の6つのドキュメントでほぼすべてをカバーできます。
| ドキュメント | 読者の疑問 | 防げるチケットの例 |
|---|---|---|
| README / クイックスタート | これは何で、どうすれば動かせるのか? | 「何から始めればいいですか?」「どのファイルをアップロードすればいいですか?」 |
| インストールガイド | 自分のサーバーに手順どおりインストールするには? | 「アップロード後に真っ白なページが表示される」「データベース接続エラー」 |
| 設定リファレンス | 各設定や環境変数は何をするのか? | 「メールが送信されない」「通貨を変更するには?」 |
| ユーザーガイド | アプリでこの作業をするには? | 「スタッフを追加するには?」「レポートはどこにありますか?」 |
| カスタマイズガイド | コードを安全に変更するには? | 「ロゴを変更するには?」「項目を追加するには?」 |
| トラブルシューティングとアップグレードノート | 何かが壊れた、または新しいバージョンにしたい | 「アップデート後に500エラー」「キューのジョブが実行されない」 |
ドキュメントはダウンロードファイルに同梱し(docs/フォルダーまたはHTMLファイル)、同じ内容をオンラインでも公開しましょう。エラーメッセージを検索する購入者は公開ページを見つけられますし、インターネットに接続できないサーバーを使う購入者もローカルのコピーを読むことができます。
まずは購入者向けのREADMEから
リポジトリのREADMEは、おそらく自分自身のために書かれたものでしょう。購入者向けのREADMEは、最初の画面で別の疑問に答える必要があります。
- これは何かを一文で。
- 動作要件:言語のバージョン、拡張機能、データベース、cron、キュー、そして有料のサードパーティサービスの有無。
- ZIPの中身:どのフォルダーをアップロードするのか、どれがドキュメントか、どれが任意か(デザインファイル、サンプルデータ)。
- アプリを動かすまでの最短ルート:5〜10行で示し、完全なインストールガイドへのリンクを添えます。
- インストーラーが作成するデフォルトのログイン情報と、それを変更するよう促す注意書き。
- サポートの受け方:ドキュメントへのリンク、サポートチケットの起票方法、チケットに含めるべき情報。
- バージョンと変更履歴へのリンク。
インストールガイドのテンプレート
インストールガイドは、ほかのすべてを合わせたよりも多くのチケットを防ぎます。記憶に頼って書くのではなく、クリーンなサーバーに製品をインストールしながらメモを取って書きましょう。次の構成を使ってください。
- 始める前に。購入者がチェックできるリスト:サーバーへのアクセス権、PHPまたはランタイムのバージョン、必要な拡張機能、データベースとそのデータベースに対する全権限を持つユーザー、サーバーを指すドメイン、SSL証明書、cronジョブを設定できる環境。
- ファイルをアップロードする。どのフォルダーをどこに置くのか、どのフォルダーをWebルートにする必要があるのか(Laravelアプリなら
public/)を正確に記載します。Webルートを変更できない共有ホスティング向けの注意書きも加えましょう。 - 依存関係をインストールする(同梱されていない場合)。
composer install --no-dev --optimize-autoloaderのように、正確なコマンドを示します。 - 環境ファイルを作成する。
.env.exampleを.envにコピーし、変更が必要な値を列挙します。 - ファイルのパーミッションを設定する。書き込み可能にする必要があるディレクトリ(たとえば
storage/やbootstrap/cache/)を明記し、777を勧めるのではなく、その理由を説明します。 - インストーラーまたはマイグレーションを実行する。ライセンスキーの入力ステップも含め、インストーラーの各画面で何を求められるかを示します。
- スケジュールタスクとキューを設定する。正確なcronの記述と、キューワーカーの実行または監視の方法を示します。
- 初回ログインと最初の作業。デフォルトの認証情報、最初に変更すべき3つの設定、テストメールの送信方法。
- インストールを確認する。「ダッシュボードが表示される」「テストメールが届く」「スケジュールタスクがログに記録される」など、この時点で動作しているはずの項目の短いリスト。
- うまくいかなかった場合:トラブルシューティングページにある、よくあるインストールエラー上位5件へのリンク。
サポートしている一般的なホスティング環境ごとに、短い個別のセクションを追加しましょう。NginxのVPS、ApacheのVPS、cPanelの共有ホスティング、Dockerなどです。サポートしていない環境があれば、そう明記します。購入者はLaravelのWebアプリをVPSにインストールする方法などのガイドで一般的な手順を学ぶこともできますが、それでも自社のガイドでは製品固有の手順をカバーする必要があります。
.envのコメントだけでなく、設定リファレンスを書く
.env.exampleのコメントは開発者には役立ちますが、購入者の多くは事業主や経験の浅い開発者です。リファレンス表があれば、「これは何をするもので、いつ変更すべきか」という疑問に1か所で答えられます。
| 変数 | デフォルト | 役割 | 変更するタイミング |
|---|---|---|---|
APP_URL | http://localhost | リンクやメールで使われるベースURL | 必ず変更し、httpsを付けた実際のドメインを設定します |
MAIL_MAILER | log | メールの送信方法 | 本番公開前にsmtpまたは利用するプロバイダーに設定します |
QUEUE_CONNECTION | sync | バックグラウンドジョブを即時実行するか、ワーカーで実行するか | アクセスの多いサイトではdatabaseまたはredisを使い、ワーカーを実行します |
APP_TIMEZONE | UTC | 日付とスケジュールタスクのタイムゾーン | 自社の業務上のタイムゾーンに設定します |
上の表は一例です。製品が読み込むすべての変数をドキュメント化してください。アプリ内の設定画面についても同様に、各設定が何を変えるのか、安全なデフォルト値は何かを記載します。
トラブルシューティング:実際のエラーメッセージを軸に項目を書く
購入者は、画面に表示されたテキストをそのまま検索します。そうした文字列をそのまま見出しに使ったトラブルシューティングページは、検索エンジンからも、購入者自身のサイト内検索からも見つけてもらえます。すべての項目で次の形式を使いましょう。
エラー:
SQLSTATE[HY000] [2002] Connection refused意味:アプリがデータベースサーバーに接続できません。
よくある原因:
DB_HOSTまたはDB_PORTの誤り、データベースサービスが起動していない、ホストがlocalhostからの接続しか受け付けていない。解決方法:
.envの値を確認し、データベースが起動していることを確かめ、localhostの代わりに127.0.0.1を試してから、設定キャッシュをクリアします。
まずは、すでに把握しているエラーから始めましょう。デバッグを無効にした状態での真っ白なページ、アップロード後の500エラー、storageのパーミッションエラー、PHP拡張機能の不足、メール認証の失敗、cronが実行されない問題、ライセンス認証の失敗などです。その後は、チケットによって新しいエラーが判明するたびに項目を追加していきます。
カスタマイズガイド:「Xを変更するには」に答える
カスタマイズの依頼はチケットの発生源として2番目に大きく、多くの販売者はそれに1件ずつ延々と回答し続けています。よくある変更トップ10を一度ドキュメント化しましょう。
- ロゴ、配色、アプリ名を変更する。
- メールテンプレートと通知文を編集する。
- 言語や翻訳文字列を追加・編集する。
- フォームとデータベースに項目を追加する。
- メニュー項目やページを追加する。
- 通貨、日付形式、数値形式を変更する。
- 別の決済、SMS、メールのプロバイダーに接続する。
- ロールや権限を追加する。
それぞれについて、ファイルの場所、変更する内容、そして今後のアップデートでも変更を維持する方法を示します。最後の点は重要です。購入者がコアファイルを編集すると、アップデートのたびにサポートチケットが発生します。代わりに、拡張ポイント、オーバーライド用フォルダー、または設定を使うよう案内しましょう。サポート、アップデート、バージョン管理のガイドでは、カスタマイズされた環境でもアップグレードできるリリースの設計方法を解説しています。
毎月、チケットをドキュメントに変える
ドキュメントは古くなるものですし、最初からすべてを網羅できることはありません。シンプルな月次サイクルで、ドキュメントを役立つ状態に保ちましょう。
- すべてのチケットにタグを付けます。カテゴリーは、インストール、設定、使い方、カスタマイズ、バグ、購入前、その他です。
- 月に一度、タグを集計します。バグ以外で最も多い質問を3つ選びます。
- それぞれに答えられたはずのページを書くか改善します。見出しには購入者自身の言葉を使います。
- 以後のチケットにはリンクで回答します。一行の要約を添えましょう。リンクで解決しなければ、そのページには改善が必要です。
- 同じ混乱が繰り返し起きる場合は、製品を修正します。よりわかりやすいエラーメッセージやインストーラーのチェックは、どんなドキュメントにも勝ります。
例として、月に40件のチケットを受けている販売者が、そのうち15件がメール設定に関するものだと気づいた場合、優れたページを1つ用意し、テストメールを送信するステップをインストーラーに加えるだけで、たいていその大部分をなくすことができます。
製品そのものに説明させる
最良のドキュメントとは、購入者が開く必要すらないものです。
- インストーラーのチェック機能:PHPのバージョン、拡張機能、書き込み可能なフォルダー、データベース接続をテストし、失敗した理由をわかりやすい言葉で説明します。
- 役に立つエラーメッセージ:次に何をすべきかを伝えます(「メールサーバーがログインを拒否しました。設定でMAIL_USERNAMEとMAIL_PASSWORDを確認してください」)。
- システムステータスページ:管理画面でバージョン、キューの状態、cronの最終実行、ストレージのパーミッションを表示します。購入者はチケットを起票するときにそのスクリーンショットを撮れます。
- インラインのヘルプテキスト:誤解しやすい設定の横に表示します。
- 空の状態の表示:次に取るべき行動を説明します(「スタッフがまだいません。最初のスタッフを追加しましょう」)。
ドキュメントをわかりやすくする書き方のルール
- 順番に行う作業には番号付きの手順を使い、1つの手順には1つの操作だけを書きます。
- 正確なコマンドと正確なパスを示し、どこで実行するかを明記します。
- 重要な手順の後には期待される結果を記載し、問題が起きたときに読者が気づけるようにします。
- 設定画面にはスクリーンショットを使い、インターフェースが変わったら更新します。
- 短い文の平易な米国英語で書きます。購入者の多くは翻訳ツールを通して読んでいます。
- ドキュメントをバージョン管理します。特定のバージョンにのみ該当するセクションには印を付け、すべてのリリースについてアップグレードノートを残します。
無料で公開されているWrite the Docsのドキュメント原則は、明確さと構成を確認するための優れたチェックリストです。
申請前のドキュメントチェックリスト
- READMEが、製品の概要、動作要件、ZIPの中身、クイックスタート、デフォルトのログイン情報、サポートの受け方に答えている。
- インストールガイドがクリーンなサーバーでテスト済みで、サポートする各ホスティング環境のセクションがある。
- 設定リファレンスが、すべての環境変数と重要な設定をカバーしている。
- ユーザーガイドが、各ロールの主な作業をカバーしている。
- カスタマイズガイドが、よくある変更トップ10と、アップデート後もそれを維持する方法をカバーしている。
- トラブルシューティングページが、正確なエラーメッセージを見出しに使っている。
- 変更履歴とアップグレードノートが含まれている。
- ドキュメントがダウンロードファイル内とオンラインの両方にある。
申請する前に、製品申請チェックリストとAppTrovoのコード基準と照らし合わせてください。ドキュメントが整ったら、掲載ページの動作要件セクションからリンクできます。これは購入前の検討者にも役立ちます。
よくある質問
顧客向けのソフトウェアドキュメントには何を含めるべきですか?
最低限、README、インストールガイド、設定リファレンス、ユーザーガイド、カスタマイズガイド、そしてアップグレードノートを含むトラブルシューティングページです。各ドキュメントはそれぞれ異なる疑問に答えるものなので、別々に分けて相互にリンクしましょう。
ドキュメントはZIPに含めるべきですか、それともオンラインに置くべきですか?
両方です。ZIP内のコピーは、購入者が持っているバージョンと常に一致します。オンラインのコピーは検索可能で、サポートの返信からリンクしやすく、リリースの合間にも更新できます。オンラインの各ページがどのバージョンに対応するのかを明確にしましょう。
インストールガイドはどの程度詳しく書くべきですか?
Webアプリをインストールした経験はあるものの、あなたの製品は初めてという人が、あなたに問い合わせることなく最後まで完了できる程度の詳しさが必要です。正確なコマンド、パス、必要なパーミッション、そして重要な各手順の後に期待される結果を含めましょう。動作要件が変わるリリースのたびに、クリーンなサーバーでテストしてください。
どのドキュメントから書けばよいかは、どう判断すればいいですか?
サポートチケットと購入前の質問を確認しましょう。通常はインストールと設定が最優先で、次によくあるカスタマイズの依頼が続きます。まだチケットがない場合は、クリーンなサーバーに自分で製品をインストールし、考え込んだ箇所をすべてドキュメント化してください。
優れたドキュメントで本当に返金は減りますか?
インストールの失敗と期待とのずれは、購入者が返金を求めるよくある理由です。明確な動作要件とテスト済みのインストールガイドは、その両方に対処します。AppTrovoでの返金は返金ポリシーに従いますが、問題を未然に防ぐほうが、依頼に対応するよりも常に低コストです。