あけましておめでとうございます。

ソフトウェアを開発し公開する場合，ドキュメント（マニュアル）を作成することが求められます。しかし，良いドキュメントを作成する方法というのはあまり知られていません。どのようにすれば良いドキュメントを作成できるのでしょうか？

本稿では，ソフトウェアと同じくドキュメントを要素と性質に構造化することで，良いドキュメントを作成する方法を紹介します。そして，その要素と性質に対してアプローチを行っているESDocというJavaScript（ECMAScript2015）向けのドキュメンテーションツールについても簡単に紹介します。

対象とするドキュメント

ドキュメントと一口にいっても仕様書，設計書，マニュアルなど様々な種類が存在します。そこで，本稿が対象とするドキュメントを「ライブラリやフレームワークなどを開発するソフトウェア開発者自身が，そのソフトウェアの使い方をエンドユーザ（そのソフトウェアを使用するほかの開発者）に向けて書くもの」とします。

このようなドキュメントは一般的にマニュアルと呼ばれます。具体的にはREADMEやAPIリファレンス，チュートリアルなどです。ソフトウェア開発者ならば日々これらのマニュアルを読んでいることでしょう。以降，本稿でドキュメントといえばこのようなマニュアルを指すこととします。

ドキュメントを書くための技術

ソフトウェアの世界にはドキュメントを書くためのたくさんの技術があります。最も古くからある技術で，かつ最も有名なものの一つとしてHTMLがあります。最近ではMarkdown，reStructuredText，AsciiDoc，Re:VIEWなど，様々な記法も使われています。

他にもPerl，Ruby，Java，Goなどの言語標準のドキュメンテーションツールとして，PerlDoc，RDoc，Javadoc，GoDocなどが存在します。言語標準以外にもYARD，JSDoc，PhpDocumentorなどがあります。これらのツールでは独自に記法を定義したり，HTMLなどの記法を組み合わせたりといった，その言語を対象にしたドキュメントを書きやすくするための工夫がなされています。

ドキュメントを書く場所としてREADMEは以前から使われていましたが，GitHubの出現によりその重要性が格段に高くなったと言えます。また，GitHubにはGitHub PagesやWikiが標準で付属しているため，Webでドキュメントを公開して運用するコストも非常に低くなりました。最近ではRead The DocsやGitBookなどGitHubと連携してドキュメントを公開できるサービスも存在します。

そしてドキュメントの間違いをチェックするツールとして，RedPenやtextlintなどの校正ツールも開発されています。

ドキュメントを書くための技術とソフトウェア開発の類似性

先ほど紹介したドキュメントを書くための技術は次のように整理できます。

• 言語：HTML，Markdown，reStructuredText，独自のドキュメントコメントなど
• 場所：GitHub，Read The Docs，GitBookなど
• 検査：RedPen，textlintなど

また，ソフトウェア開発も同じように整理できます。

• 言語：Ruby，Java，JavaScriptなど
• 場所：GitHub，BitBucketなど
• 検査：Lintツール，コーディング規約，コードフォーマッターなど

このように言語，場所，検査を軸にして整理することで，ドキュメントを書く技術とソフトウェア開発は類似していることがわかります。

しかし，ドキュメントを書く技術とソフトウェア開発では大きな違いがあります。それは，ソフトウェア開発ではソフトウェアを要素と性質に構造化するという重要な取り組みを行っている点です。この要素と性質というのは次のようなものです。

• 要素：GoFのデザインパターンやMVCに代表されるようなコードそれぞれの役割
• 性質：保守性，可用性，信頼性，障害耐性など

ソフトウェア開発ではこれらの要素と性質に対してどのようにアプローチすれば，良い物を作れるかを考えながら開発を行っています。ではドキュメントを書くときはどうでしょうか？ 要素と性質という構造に着目すると良いドキュメントを書けるのではないでしょうか？

ドキュメントの要素と性質

そこで筆者はドキュメントも要素と性質に構造化することを考えました。そしてその要素と性質をそれぞれ次の5つに整理しました。

要素

• 導入：ソフトウェアのインストール方法，環境構築の方法など
• 操作：ソフトウェアの実行方法，設定の方法，チュートリアルなど
• 参照：ソフトウェアのAPIリファレンス，網羅的な設定項目など
• 事例：ユースケースに応じた使い方や設定方法のサンプル，スクリーンショットやデモ動画など
• 履歴：これまでの変更履歴，リリースの内容など

性質

• 継続性：ドキュメントが継続的に保守されているかどうか
• 網羅性：ソフトウェアについて抜けも漏れなく書かれているかどうか
• 正確性：ソフトウェアについて正しく書かれているかどうか
• 関連性：関係するドキュメントが相互に紐付いているかどうか
• 検索性：ドキュメント内を検索できるかどうか

このように整理した要素と性質に対してアプローチすることで，良いドキュメントが書けるのではないかと考えています。

そこで以降では筆者が開発しているESDocというJavaScript向けのドキュメンテーションツールを紹介します。ESDocはこの要素と性質に対してアプローチを行うことで良いドキュメントを書くためのツールを目指しています。