製品はロケット用のソフトウェアよりもシンプルですが、技術的には洗練されています。 新しいバージョンのインターフェイスがシンプルになるように一生懸命努力しますが、何かを理解せずにドキュメントにアクセスするユーザーが常にいることを認識しています。 したがって、ドックが必要であり、製品の印象を損なわないために、便利で便利なはずです。
私たちには6つの製品があり、そのドキュメントは会社のまさにその基礎から開発者によって書かれました。 半年间、私たちは古い 記事を書き直し、 新しい記事を書いてきました。 カットの下-これをうまく行うのに役立つ50の質問。 しかし、最初に、少し紹介します。
文書化が重要である理由と誰がそれを行うべきか
良いドックを作るのは難しいです。 どこかでアナリスト、ライター、エディターの巨大な部門がそれに取り組んでおり、どこかで開発者がドックに書き込んでいます（完了-説明）。
複数のバージョンを持つ6つの製品に2人のテクニカルライターがいます。 これだけでは十分ではないため、プロダクトマネージャー、テスター、サポートの最前線、マーケティングがドックで行われます。 彼らは記事を書くことはしませんが、クライアントの製品とタスクを理解し、トピックを選択して情報を収集し、完成した記事の内容とデザインを確認するのに役立ちます。 一緒にドックを改善します。
テクニカルライターの小規模な部門がある場合は、他の部門から従業員を募集します。 興味がない場合は、以下のリストから引数を与えてください。 最初のサポート、2番目と3番目のマーケティングおよび製品マーケティング。 それでは、なぜドキュメントが重要なのでしょうか？
- サポートファクター 。 理由の最初で最も明白な。 ドキュメントに問題がない場合、ほとんどのお客様はサポートに連絡せずに問題を解決します。 残りのサポートは、指示へのリンクをスローするか、自分ですぐに確認します。 完全なドキュメントを使用して、チャットボットを作成できます。 これにより、顧客への応答時間が短縮され、顧客満足度が向上し、サポートコストも削減されます。
- 選択係数 。 ドキュメントは、価格、利便性、機能とともにクライアントの選択に影響します。 これは、 ISPmanagerとDCImanagerユーザーの調査とフィードバックによって確認されています 。 このように、ドックはサポートの必要性がなくなりますが、マーケティングの一環として競争上の優位になります。
- ロイヤリティ係数 。 クライアントが開始時または処理中にドックを理解せずに去った場合、これは問題です。 顧客を引き付けることは、品物が悪いために失うには高すぎる。
適切なドキュメントを作成する方法
目標を定義します。 これが最も苦痛です。 説明のためだけに機能を説明したり、インターフェイスにコメントしたりすることは目標ではありません。 目標は常に有用なアクションです。 記事を読んだ後、ユーザー、管理者、または開発者は何を知り、何をすべきでしょうか？ たとえば、サイトを作成してドメインをバインドし、SSL証明書を発行し、バックアップを構成します。つまり、問題を解決します。
聴衆を知る 。 顧客をユーザー、管理者、開発者に分けます。 しかし、これは有用なテキストを作成するには十分ではありません。 オーディエンスをすばやく理解するには、UXと製品にアクセスし、トピックに関するサポートリクエストとその回答を調べ、ファーストラインコールを聞き、サイトとブログを見てください（マーケティングも必要なことを書いています）。 そして、その後にのみ書き始めます。
確認、編集、もう一度確認します。 テクニカルライターは最初のチェックを行う必要があります。 彼女のあともう一つ。 次に、サポート、マーケティング、その他の部門を監査に結び付ける価値があります。 次に、スタイルおよびデザインガイド（編集ポリシー）を確認する必要があります。 側からの誰かまたは別の技術ライターが彼に最終的な校正をさせました。 編集者がいる場合は、彼がこのステージを担当します。
編集方針について
編集ポリシーでは、プレゼンテーションのスタイル（公式または非公式）、レイアウトとデザイン（スクリーンショット、そのサイズ、テーブルスタイル、リスト）、および物議を醸す問題（eまたはe、用語のつづり）を規定しています。 そのようなドキュメントがまだない場合は、必ず行ってください。時間を短縮し、順序を復元します。 インスピレーションと理解については、YandexカンファレンスのレポートとIBMまたはMailchimpのマニュアルの例を参照してください。
出版後に記事を配布します 。 ドキュメントが書かれている場合、おそらく誰かがそれを必要とします。 それを光に見せて最大限に活用してください：翻訳、製品の参照、マーケティングへの提供、サポート。 テーブルに書き込まないでください。
ドックで作業するための50の質問
ドキュメントの作成中に、同じ間違いを繰り返しました。 彼らは記事のチェックに多くの時間を費やし、最初は万能薬のようでしたが、問題はアプローチと内容にあったため、ガイドは助けにはなりませんでした。 テクニカルライターがすぐに記事を思いつくことができるように、私たちが絶えず尋ねた（または忘れた）質問をすべてまとめました。 ドックを書く場合にも使用します。
目標
1.誰のために記事を書いていますか？ ユーザー、管理者、開発者の将来の読者はだれですか？
2.どのようなタスクに直面していますか（実行すべきジョブ）。 その人の説明はありますか？
3.このユーザーのトレーニングのレベルはどのくらいですか？ 彼はすでに何を知っていますか？ 彼にとって明らかでないことは何ですか？
4.初心者ユーザーにこれを説明すると同時に、基本的なことの高度な説明を怒らせないようにするにはどうすればよいですか？
5.ユーザーが記事の主要な内容を理解するために、他に何を説明する必要がありますか？
6.この記事はドキュメントのどのセクションに適していますか？
7.この記事またはその一部を他のセクションに複製する必要がありますか？
8.どの記事にリンクする必要がありますか？
9.この記事にビデオチュートリアルを添付する必要があるかもしれません。
情報源
10.現在のユーザーは記事のトピックに問題がありますか？
11.現在、サポートは何を行う必要があるかをどのように説明していますか？
12.マーケティング部門は、このトピックに関するブログ記事やニュースを書きましたか？ 言葉遣いや構造などを「スパイ」することは可能ですか？
13.サイトにこのトピック専用のセクションはありますか？
14.スクリプトにはUXとプロダクトマネージャーが含まれていましたか？ なぜこれをしたのですか？
15.競合他社はこの質問をどのように説明しますか？
16.まだどの領域でベストプラクティスを確認できますか？
コンテンツチェック
17.記事の目的を達成しましたか？
18.上級ユーザーにとってすべてが明確になりますか？
19.初心者ユーザーにとってすべてが明確になりますか？
20.すべてが論理的で一貫していますか？ ジャンプや深byはありませんか？
21.アクションのシーケンスは正しいですか？ ユーザーはこの指示に従うだけで目標を達成できますか？
22.すべてのケース/ユーザーパスを考慮しましたか？
23.記事は選択したセクションに収まりますか？
レイアウトチェック
24.読めないテキストシートはありますか？ 回路を交換することは可能ですか？
25.長い段落はありますか？
26.短すぎる段落はありますか？
27.リストが長すぎますか？
28.認識するには複雑すぎるリスト（2つまたは3つ以上のレベルを持つリスト）はありますか？
29.十分な画像がありますか？
30.画像が多すぎませんか？ あまりにも明白な手順を説明していますか？
31.スキームがある場合、それらは理解可能ですか？
32.テーブルは認識しにくいですか？
33.ページ全体は見栄えが良いですか？
文学編集
34.すべてがガイドに従って設計されていますか？
35.残りのドキュメントのスタイルは一貫していますか？
36.単純化できる提案はありますか？
37.明確化が必要な複雑な用語はありますか？
38.事務主義はありますか？
39.繰り返しはありますか？
40.聴力を損なうものはありませんか？
最終校正
41.タイプミス、スペルミス、句読点のエラーはありますか？
42.ハイフン、段落、およびセクションは大丈夫ですか？
43.すべての画像が購読されていますか？
44.インターフェイス要素の名前は正しいですか？
45.どこにでもリンクがありますか？ 彼らは働き、どこへ行くのですか？
公開直後
46.記事には、他の記事に「プル」されるセクションがありますか？ ある記事の変更が他の記事に自動的に適用されるように、マクロで装飾されていますか？
47.この記事は他のセクションから参照されるべきですか？ もしそうなら、どれですか？
48.この記事へのクイックリンクを製品に追加する必要がありますか？
49.サポート、マーケティング、または他の部門へのリンクを送信する必要がありますか？
50.翻訳のために記事を提出する必要がありますか？
このリストは、印刷してデスクトップに置いたり、壁に掛けたりすることができます。 またはチェックリストに変えます。 質問のいくつかはビジネスプロセスに持ち込むことができます。 たとえば、私たちのものはYouTrackの一般的な開発プロセスで修正されています。 文書化のタスクは、さまざまな段階と部門を経て、文書化された文書なしではリリースする機能を提供できません。