開発者がなぜドキュメントをスキップしてはいけないのか

モバイルアプリ、Webアプリ、デスクトップアプリ、またはJavaScriptライブラリの開発領域では、ドキュメントがソフトウェアの開発の成功を左右する重要な役割を果たします。しかし、あなたがドキュメンテーションをしたことがあるならば、あなたはそれが開発者がすることはほとんど好きではないことであると私に同意するでしょう.

コードを書くのとは異なり（開発者がサインアップしたものです）、ドキュメンテーション（我々はそうではありませんでした）はそうする必要があり、そして簡単に消化されるべきです。 みんな. 技術的には、私たちは機械語（コード）を人間が理解できる言語に翻訳しなければなりません。.

それは本当に面倒なことかもしれませんが、ドキュメントを書くことは重要であり、あなたのユーザー、あなたの同僚、そして特にあなた自身に利点をもたらすでしょう。.

良いドキュメントはユーザを助ける

ドキュメンテーションは読者を助けます コードの仕組みを理解する, 明らかに。しかし、多くの開発者は、ソフトウェアのユーザーが熟練していると想定することを間違えています。したがって、ドキュメントは最初から含まれているべきである必要不可欠な要素の多くをスキップして、薄い材料かもしれません。あなたがその言語に精通しているならば、あなたはあなた自身の主導で物事を理解することができます。そうでなければ、あなたは失われます.

ユーザーを対象とした文書は通常、実用的な使用法または “の仕方”. 一般ユーザー向けのドキュメントを作成する際の経験則は、 それは明確なはずです. 専門用語や専門用語よりも、人に優しい言葉を使用することをお勧めします。実際の使用例も大歓迎です.

優れたレイアウト設計は、ユーザーが目の疲れることなくドキュメントの各セクションをスキャンするのにも役立ちます。いくつかの良い例（別名私のお気に入り）はBootstrapとWordPressのドキュメントです。 “WordPressの最初のステップ”.

それはあまりにも他の開発者を助けます

各開発者は独自のコーディングスタイルを持ちます。しかし、チームで働くことになると、私たちはしばしば他のチームメイトとコードを共有しなければならないでしょう。だからそれは不可欠です 標準について合意する 全員を同じページに配置する。適切に書かれた文書は、チームが必要とする参照です。

しかし、エンドユーザー向け文書とは異なり、この文書では通常、 技術的な手順 コード命名規則のように、特定のページをどのように構成する必要があるか、およびAPIがコード例とともにどのように機能するかを示します。多くの場合、我々はコードとインラインでドキュメントを書かなければならないでしょう。 コメント）コードが何をしているのか説明する.

また、お持ちの場合 新しいメンバーが参加する あなたのチームが後で、このドキュメントはそれらを訓練するための時間的に効果的な方法であるかもしれないので、あなたは彼らにコードの1対1のランダウンを与える必要はありません.

奇妙にもそれはコーダーを助けます

コーディングについてのおもしろいことは時々それが 開発者自身も彼らが書いたコードを理解していません. これは、コードが何ヶ月も、あるいは何年もの間手付かずのまま残されている場合に特に当てはまる.

何らかの理由でコードを再検討する必要が突然発生した場合、これらのコードを書いたときに何が起こっていたのかという疑問が残るでしょう。驚くことではありません。私は以前この状況にいました. これは 正確に 私がいるとき 願った 私は自分のコードを正しく文書化しました.

コードを文書化することで、フラストレーションなしにコードの最後にすばやくアクセスできるようになり、変更を取得するために費やすことができる時間を大幅に節約できます。.

優れた文書化に必要なもの?

適切な文書を作成するには、いくつかの要因があります。.

仮定しない

ユーザーが何を知っていると思い込まないでください。 君は 何でも知っている 彼ら 知りたい。いつでもいい 最初から始める ユーザーの熟練度に関係なく.

たとえば、jQueryプラグインを作成した場合は、SlickJSのドキュメントからヒントを得てください。 HTMLの構成方法、CSSとJavaScriptの配置場所、jQueryプラグインの最も基本的なレベルでの初期化方法、さらにこれらすべてを追加した後の完全な最終マークアップも示しています。これは明らかなことです。.

要するに、ドキュメントは開発者ではなく、ユーザーの思考プロセスで書かれています。このようにあなた自身のドキュメントに近づくことはあなた自身の作品をまとめる際により良い見通しをあなたに与えるでしょう.

2.標準に従う

コードとインラインになるドキュメントを追加する, その言語で期待されている標準を使用する. それぞれの関数、変数、そして関数から返される値を記述することは常に良い考えです。これはPHPの良いインラインドキュメントの例です。.

 / ** *カスタムクラスをボディクラスの配列に追加します。 * * @param array $ classes body要素のクラス。 * @return配列* / function body_classes（$ classes）//複数の出版された著者を含むブログにグループブログのクラスを追加します。 if（is_multi_author（））$ classes [] = 'グループブログ'; $ classesを返します。 add_filter（ 'body_class'、 'body_classes'）; 

以下は、PHP、JavaScript、およびCSSのベストプラクティスを使用してインラインドキュメントをフォーマットするためのいくつかのリファレンスです。

• PHP：WordPress用のPHPドキュメント標準
• JavaScript：UseJSDoc
• CSS：CSSDoc

あなたがSublimeTextを使用しているならば、私は賢くあなたのコードにインラインドキュメントを事前に追加するDocBlockrをインストールすることを勧めます.

3.グラフィック要素

グラフィック要素を使用してください、彼らはテキストよりよく話します。これらのメディアは、特にグラフィカルインタフェースを使ってソフトウェアを構築する場合に役立ちます。矢印、円、またはのようなポインティング要素を追加できます。 推測なしで、ステップを達成するためにどこへ行けばよいかをユーザーが理解するのに役立つ可能性があるものすべて.

以下は、Towerアプリからインスピレーションを得られる例です。プレーンテキストのコマンドラインを使用するよりも理解しやすいように、バージョン管理がどのように機能するかを効率的に説明します。.

4.セクショニング

箇条書きのリストや表の中にあるドキュメント内のいくつかのものをラップすることで、長いコンテンツをスキャンしてユーザーにとって読みやすくすることができます。.

目次を追加し、ドキュメントを読みやすいセクションに分割しながら、各セクションを次のセクションに関連させます。. 短く簡潔にしてください. 以下は、Facebookで整理されたドキュメントの例です。目次で、クリックしたい場所に移動します.

5.修正と更新

最後に、ドキュメントの間違いを確認し、必要に応じて、または製品、ソフトウェア、またはライブラリに重大な変更がある場合はいつでも修正します。あなたのドキュメントはあなたの製品と一緒に定期的に更新されなければ誰にも役に立たないでしょう.