WordPressプロフェッショナル向けの製品ドキュメント

公開: 2017-07-28

製品のドキュメントは通常、重要ではないと見なされており、手抜きをすることができます。クライアントに価値を提供できるもの、または収益やマーケティングなどの主要なビジネス分野に影響を与える可能性のあるものとは見なされていません。確かに、WordPressの専門家として、AtlassianやCiscoと同じ方法でドキュメントを作成する必要はありません。通常、人々が「ドキュメンテーション」について考えるとき、彼らは、誰も読まない非常に大きな棚にアルファベット順に索引付けされた、厚く印刷されたユーザーガイドの画像を思い起こさせます。

しかし、これは変更されました：

アジャイルとDevOpsの出現により、ソフトウェアの出荷が高速化され、開発サイクルもより動的になりました。その結果、ドキュメントは、紙に静的に書かれたものではなく、最新リリースの現在の状態を反映するようになりました。ドキュメントは開発サイクルに統合されており、ソフトウェアと同じくらい頻繁に更新されます。

WordPressの専門家が製品のドキュメントを気にする必要があるのはなぜですか？

便利で最新のドキュメントは、ユーザーの生活を楽にするだけでなく、他に類を見ないマーケティング資産となる洗練されたレベルを追加します。逆に、不十分なドキュメントは悪影響を及ぼします。あなたはおそらくこれを自分で経験したことがあるでしょう：あなたはドキュメントで解決策を見つけるために一生懸命努力していた問題を抱えていました、そしてあなたがそうしなかったときあなたはイライラしました（そしておそらく怒っていました）。あなたが製品の代金を払っている場合にのみ悪化します。

WordPressエージェンシーで働いている場合、初期設計からアセットまで、プロジェクトのすべての領域にわたってドキュメントを配信すると、次のことを示すレベルのプロフェッショナリズムが追加されます。

あなたは細部に注意を払います。
あなたは余分な努力をするのに十分なほどあなたのクライアントを気にします。
あなたは透明性があり、設計と技術プロジェクトの決定に自信を持っています。

MindTouchのマーケティング担当副社長であるMikePuterbaughは、製品ドキュメントがマーケティング資産である5つの理由を説明するMashableの記事を書きました。彼は次のように結論付けました。

それはセクシーな仕事ではありませんが、それはあなたにあなたの仲間の尊敬、より効果的な会社の経営とより協力的なチームを獲得するでしょう。それは今四半期や今年ではなく、競争上の優位性と長期的な成長に影響を与えることです。

十分なモチベーションを確立したので、次のことを行います。

WordPressに関連するさまざまな種類の製品ドキュメントを調べてください。
各ドキュメントタイプのニーズについて話し合い、実用的なアドバイスを提供します。
製品ドキュメントの計画と共同作業の方法に関する最初のガイダンスを提供します。特にWordPressエージェンシーで働いている場合。

WordPress製品ドキュメントの種類

WordPress製品は、プラグインやテーマだけではありません。このセクションでは、オンラインヘルプ、REST API、およびマイクロコンテンツと呼ばれる興味深いものについても説明します。

WordPressプラグイン

WordPressプラグインのドキュメントは、ユーザーと開発者の2つの群衆に対応する必要があります。使用される文体と同様に、それぞれの文書化のニーズは異なります。

ユーザー

ユーザーのドキュメントのニーズは、主にトラブルシューティングと構成を中心に展開されます。これに加えて、ユーザーにプラグインを試してもらうために、魅力的な方法でプラグインを提示する必要があります。すべてのプラグインには、WordPressプラグイン市場に独自のページがあります。次の点に注意してください。

ダウンロードと使用を奨励する説得力のある有用な説明を書いてください。
ダッシュボードプラグインの構成ページから、説明付きの注釈付きスクリーンショットを追加します。
よくある質問に、些細なことではなく役立つ質問を入れてください。
更新され、よく書かれた変更ログを用意します。そこに不可解なメモや簡潔なメモを追加しないでください。

ユーザーがドキュメントを使用しているとき、彼らはおそらく急いで解決策を見つけることを切望していることを覚えておく必要があります。明確に、シンプルに、そして簡潔に書いてください。彼らにとって、それがすでにあるよりも難しくしないでください。

開発者

ベストソフトウェアプラクティスと公式のPHPコーディング標準に従うことに加えて、次の領域に注意を向ける必要があります。

プラグインフック

これらは、WordPressの動作を変更する作業を行います。おそらくあなたのWordPressプラグインはそれらを使用しています。プラグインフックはコードの重要な部分であるため、プラグインフックの使用方法と、プラグインが関与するWordPress機能を文書化する必要があります。

テンプレートタグ

テンプレートタグは、WordPressプラグインが機能を強化するためのもう1つの方法です。作成したテンプレートタグ関数を文書化します。他のユーザーや開発者が自分のWordPressサイトでタグをどのように使用できるかについての例を含めてください。

オプション

オプションは、特定の情報をWordPressデータベースに保存する方法です。これは、add_option関数とget_options関数を介して行われます。この場合、これらの関数に渡すパラメーターを文書化します。

データベース

プラグインは、データベースからさまざまなものを頻繁に読み書きします。これらは基本的な操作であるため、それらを文書化すると、他の開発者がプラグインの動作を理解するのに大いに役立ちます。

WordPressのテーマ

テーマのドキュメントを作成できる2つの異なる領域があります。 1つ目はソースファイルです。コメント付きのCSSファイルは、コメントなしのCSSファイルよりも理解しやすく読みやすいです。 css_docなどのツールを使用してください。これにより、JavaDocスタイルのドキュメントが生成され、公開できます。

他の領域はスタイルガイドです。これらのドキュメントでは、要素がどのように見える必要があり、どのような場合に使用する必要があるかについて説明しています。それらは一貫性を強制し、コラボレーションも容易にします。すばらしい例がたくさん含まれているので、Hubspotのブランドスタイルガイドの20のすばらしい例の記事を読むことができます。

繰り返しになりますが、公式のWordPressCSSコーディング標準を参照することを忘れないでください。

デザイン要素をこのように詳細に文書化することは、WordPressエージェンシーの場合の新人研修にも役立ちます。スタイルガイドは、新規および過去のクライアント作業のチュートリアルまたは参照資料として使用できます。

オンラインヘルプ

オンラインヘルプは特定のユーザーの問題を解決することを目的としているため、一般的なタスクと問題のリストから始めるのが最善の方法です。リストは最初は網羅的ではありませんが、できるだけ多くの具体的なアイテムを作成するために時間をかけてください。アイデアは、これらのタスクと問題のそれぞれについてオンラインヘルプファイルを作成し、それらを関連情報にハイパーリンクすることです。ユーザージャーニーを作成して、ユーザーがアプリケーション内でたどることができるさまざまなパスを計画することができます。よくある質問や問題のある領域に気付くためにサポートメールに飛び込むことは、ナレッジベースを最新かつ有用な状態に保つための良い方法です。

Spring intoTechnicalWritingの著者であるBarryJ.Rosenbergは、優れたヘルプファイルを作成するために、次のアドバイスを提供しています。

各ヘルプファイルはできるだけ短くしてください。箇条書きよりも番号付きリストを優先します。逸脱したり、脚注を付けたり、欲しがったりしないでください。各ヘルプファイルを単一の個別のタスクに集中させてください。

マイクロコンテンツ

マイクロコンテンツには2つの定義があります。1つは、特定の記事の要点を把握するために、ユーザーがスキミングするヘッドラインやセクションなどのコンテンツです。 2つ目は、独立してユーザーエクスペリエンスを向上させるために使用される小さなコンテンツです。私たちが念頭に置いている特に優れた例の1つは、Slackの「数人が入力している..」ビットです。（Slackは優れたマイクロコンテンツでいっぱいですが）。

このビットは、3人以上が同じチャネルに同時に入力しているときにトリガーされます。 Slackは、現在入力しているユーザーのリストを印刷するだけでなく、この退屈な情報を取得して、楽しみを追加します。議論は本当に熱くなり始めており、それはそれを示しています。これは、製品ドキュメント（アプリケーションメッセージはその一部ですよね？）が人々にあなたのことを話させる（そして上記のような陽気なミームを作成する）方法の優れた例です。

REST API

REST APIの文書化は、それ自体が別の技術です。すべてのテクニカルライティングと同様に、定義の簡潔さ、明確さ、および単純さを目指す必要があります。 REST APIには独自の形式と複雑さがあるため、TomJohnsonが彼のI'dRatherBeWritingブログでAPIを文書化するための優れたガイドを研究するよりも悪いことはありません。

ドキュメントの共同作業と計画

最終的に、ドキュメントは製品設計の一部である必要があります。そのため、ソフトウェアサイクルに追加のパイプラインがあるものとしてアプローチする必要があります。これは、ソフトウェアリポジトリを使用して最新のドキュメントバージョンを保存し、バグ/問題追跡システムを使用してタスクと問題を監視し、ドキュメントプロジェクトの計画をロードマップに含め、最後に他の人と協力することを意味します。開始方法の大まかな概要は次のとおりです。

ユーザーが知りたいと思うすべてのことと、テキストを書く必要がある領域を記録します。
すべてが揃ったら、それらをカテゴリにグループ化し、ドキュメントのタイトルを作成します。
タイトル、説明、対象読者、メディア（ドキュメントの形式）、長さ、所要時間などを詳細に記述した各ドキュメントの仕様を記述します。
ドキュメント仕様からの見積もりをプロジェクト計画に追加します。

製品ドキュメントはすべての領域にまたがっているため、組織内のさまざまな人々と協力する必要があることはほぼ確実です。座って、これらすべてがどのように進むかについてのある種のプロセスについて合意することは良い考えです。すべてのプロジェクトと同様に、技術支援を提供する利害関係者と、変更を確認および編集する利害関係者を特定する必要があります。

プロセスにはさまざまな段階があるはずです。これらは、情報が収集される場所、ドキュメントが作成されるとき、文学的校正の準備ができるとき、技術的なコメント、公開などのためにマップする必要があります。文学的、技術的、およびコンテンツ関連のコメントの違いを強調します。たとえば、チームリーダーにドキュメントへのコメントを依頼したり、技術的に関連する情報の代わりに文法や句読点を求めたりする場合は、あまり役に立ちません。

閉鎖

製品ドキュメントは、長期的に見返りのある資産です。それはあなたのクライアントに価値を与えます。たとえば、StripeのAPIドキュメントのように、フォーラムで人々がそれについて絶賛するほど良いかもしれません。これにより、エンゲージメントが構築され、ブランドと製品が自然で強力な方法で宣伝されます。クリエイティブなマイクロコンテンツと組み合わせると、製品のドキュメントが「マーケティングの秘密兵器」であるとマイク・プターボーが言った意味を実現します。