WordPressプラグインとテーマの文書化

公開: 2017-03-17

ドキュメントは通常、問題があり、迅速に回答が必要な場合にのみ評価されるものです。この記事では、WordPressアセットのドキュメントを作成することが、WordPress開発者としての実践にとって重要である理由と、出荷するテーマとプラグインの品質について説明します。

ドキュメントが重要なのはなぜですか？

プロジェクト、アセット、または製品に関する最新のドキュメントセットを保持することは、多くの理由で重要です。

まず、2か月前に作ったものを見て、それ以来触れていないものを見て、それが何を意味するのかわからないというのはよくある経験です。あなたがそれを開発するとき、あなたはそれをすべて頭の中に持っていますが、その理解は将来そこにはありません。したがって、インラインコードコメントを使用するか、Markdownでプレーンテキストのメモを書くことは、将来の自分自身を混乱から救うのに大いに役立ちます。

第二に、アセットを文書化しておくことは、他のWordPress開発者にとって役立ちます。そして、これはあなたが孤独なフリーランサーであっても理にかなっています（あなたはある時点で他の人と協力しなければなりません）。それらはそれらの資産を使用する必要があるか、それらを維持および/または更新するように求められます。サポートを提供したり、いくつかの難しい部分を説明したりするために周りにいない他の誰かによって書かれた文書化されていないコードを使用しなければならないことは非常にイライラします。

最後に、ドキュメントはあなたの製品に「洗練された」外観を追加し、あなたの顧客はあなたをもっと愛するでしょう。

効果的な文書化のための5つの原則

テクニカルライティングはそれ自体が専門分野であり、技術情報を明確かつ明確に伝達するために使用されます。（コンピューターだけでなく、たとえば弁護士や医師も独自の技術用語を使用します）。そのため、テクニカルライティングと見なされるドキュメントは通常、特定のスタイルに従い、一連のルールに従います。

製品の効果的なドキュメントを作成できるように、最も重要な5つを見ていきましょう。

文章で通常使用するよりも少ない単語を使用することをお勧めします。すべての単語には目的が必要です。直接的かつシンプルに。ドキュメントは通常、人が困っていてすぐに解決策を見つけたいときに求められます。たとえば、「オブジェクトQの破棄に失敗するとメモリリークが発生する」のような文は、「オブジェクトQの破棄に失敗するとメモリリークが発生する」よりも望ましいです。
受動態ではなく能動態を使用することをお勧めします。「右上のボタンをクリックする必要があります」ではなく、「右上のボタンをクリックする」。能動態を使用すると、誰が何をするかについてのあいまいさが解消されます。受動態は、被写体ではなくオブジェクトに焦点を合わせる必要がある場合にのみ使用されます（たとえば、 Pressidiumのプラットフォームはセキュリティを念頭に置いて構築されています）。
概念を説明する必要がある場合は説明言語を使用し、ステップバイステップの手順（チュートリアルなど）を説明する必要がある場合は必須の言語を使用します。
順序のないものをリストする必要がある場合は箇条書きリストを使用し、ポイントの順序が重要な場合は番号付きリストを使用します。
指示を提示する前に、自分で指示をテストしたことを確認してください。

WordPressプラグインの文書化

WordPressプラグインは、他のソフトウェアと同じです。それらは特定の機能を提供し、インストールが必要であり、場合によってはトラブルシューティングも必要です。すべてのユーザーが同じ技術的専門知識を共有しているわけではないため、どれほど単純であっても、適切な量のドキュメントを提供することをお勧めします。

WordPressプラグインをwordpress.orgに公開すると、インストール手順、スクリーンショット、FAQ、さらには変更ログを配置する場所が提供されます。プラグインの人気を高めるには、有用で質の高い情報を入力することが重要です。

最終的にユーザーがプラグインをダウンロードしてWebサイトにアクセスできるようにする、説得力のある有用な説明を記述します。
プラグインの各構成アイテムを説明する注釈付きのスクリーンショットを、プラグインがブラウザーでどのように表示されるかを示すスクリーンショットに追加します。
些細なことではない質問をFAQに入れてください。奇妙なエッジケースを発見する良い方法は、コンピューターに精通していない友人にプラグインを使用するように依頼することです。
更新され、よく書かれた変更ログを用意します。簡潔で不可解なワンライナーは大したことではなく、ユーザーを本当に気にしていないことを示しています。
プラグインのコードに十分なコメントが付けられており、ソフトウェアのベストプラクティスと公式のコーディング標準に従っていることを確認してください。

行き詰まっていてインスピレーションが必要な場合は、簡単な調査を行って、あまり使用されていないプラグインと比較して、数十万のインストールがある人気のあるプラグインでテキストがどのように記述されているかを確認してください。

WordPressテーマの文書化

WordPressのテーマを文書化することはまったく別の問題です。 WordPressテーマの最も一般的な問題は、どのセクションがどの視覚要素に対応しているかがわからないことです。誰もがCSSに精通しているわけではありません。

CSSのすべてのセクションの階層を、対応する説明とともに作成します。
セクションごとに、小さな例とともに、各機能の詳細を示す注釈付きのスクリーンショットを追加します。ユーザーが指示に従う必要があることを行う方法を示すときは、能動態と命令型言語を使用することを忘れないでください。
css_docなどのツールを使用してください。これにより、JavaDocスタイルのドキュメントが生成され、公開できます。
コードコメントだけでは不十分な場合があり、CSSテーマのスタイルガイドドキュメントを作成する必要があります。スタイルガイドドキュメントでは、要素がどのように見える必要があり、どのような場合に使用する必要があるかについて説明しています。それらは一貫性を強制し、コラボレーションも容易にします。 Googleによるこの例を参照してください。
ブループリントCSSのようなCSSフレームワークを使用します。これは、カスタマイズ可能なグリッド、機能するデフォルトのタイポグラフィ、ブラウザーのCSSリセットなどの一連のツールを提供することにより、開発に役立ちます。
繰り返しになりますが、公式のWordPressCSSコーディング標準を参照することを忘れないでください。