分12あけましておめでとうございます。ソフトウェアを開発し公開する場合,ドキュメント(マニュアル)を作成することが求められます。良いドキュメントを作成する方法というのはあまり知られていません。どのようにすれば良いドキュメントを作成できるのでしょうか?本稿では,ソフトウェアと同じくドキュメントを要素と性質に構造化することで,良いドキュメントを作成する方法を紹介します。その要素と性質に対してアプローチを行っている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の出現によりその重要性が格段に高くなったと言えます。PagesやWikiが標準で付属しているため,Webでドキュメントを公開して運用するコストも非常に低くなりました。DocsやGitBookなどGitHubと連携してドキュメントを公開できるサービスも存在します。ドキュメントの間違いをチェックするツールとして,RedPenやtextlintなどの校正ツールも開発されています。先ほど紹介したドキュメントを書くための技術は次のように整理できます。Docs,GitBookなど検査:RedPen,textlintなどまた,ソフトウェア開発も同じように整理できます。言語:Ruby,Java,JavaScriptなど場所:GitHub,BitBucketなど検査:Lintツール,コーディング規約,コードフォーマッターなどこのように言語,場所,検査を軸にして整理することで,ドキュメントを書く技術とソフトウェア開発は類似していることがわかります。ドキュメントを書く技術とソフトウェア開発では大きな違いがあります。それは,ソフトウェア開発ではソフトウェアを要素と性質に構造化するという重要な取り組みを行っている点です。この要素と性質というのは次のようなものです。性質:保守性,可用性,信頼性,障害耐性などソフトウェア開発ではこれらの要素と性質に対してどのようにアプローチすれば,良い物を作れるかを考えながら開発を行っています。要素と性質という構造に着目すると良いドキュメントを書けるのではないでしょうか?ドキュメントの要素と性質そこで筆者はドキュメントも要素と性質に構造化することを考えました。その要素と性質をそれぞれ次の5つに整理しました。継続性:ドキュメントが継続的に保守されているかどうか網羅性:ソフトウェアについて抜けも漏れなく書かれているかどうか正確性:ソフトウェアについて正しく書かれているかどうか関連性:関係するドキュメントが相互に紐付いているかどうか検索性:ドキュメント内を検索できるかどうかこのように整理した要素と性質に対してアプローチすることで,良いドキュメントが書けるのではないかと考えています。そこで以降では筆者が開発しているESDocというJavaScript向けのドキュメンテーションツールを紹介します。ESDocはこの要素と性質に対してアプローチを行うことで良いドキュメントを書くためのツールを目指しています。JavaScript著者プロフィール丸山亮(まるやまりょう)Cookpad株式会社所属。サービスオーナー兼エンジニアとしてサービス開発を行っている。個人ではJavaScript関係のツールを作ったり,CodeLunch.fmというポッドキャストをしている。趣味は料理と民芸食器を集めること。2019」を開催しました。DAY1・DAY2の様子を注目セッションとともにお伝えします。LINEのエンジニア3名がイベントに先駆けて見どころを紹介します。コードの安全性・安定性を高める開発サイクル~テスト管理の効率を上げ,脆弱性診断を自動で行う~本連載では,連載「業務を改善する情報共有の仕掛け」を受けつつ,安全性・安定性を加えた開発サイクルについて考えていきます。若者世代から圧倒的な人気を誇るライブ配信&動画投稿コミュニティアプリ「MixChannel」(ミクチャ)の裏側(レコメンドシステムやサーバサイド開発など)について解説していきます。その他の連載CSS3アニメーションでつくるインターフェイス表現CSS3によるアニメーション表現を紹介していきます。その中でも,幅広い読者に応用してもらえるだろうインターフェイスを主なお題とします。MySQL道普請便り本連載では,MySQLを使ったアプリ開発・運用に関するノウハウをご紹介していきます。RecipeUbuntuの強力なデスクトップ機能を活用するための,いろいろなレシピをお届けします。JavaScriptセキュリティの基礎知識JavaScriptに関するセキュリティ上の問題はどこで発生し,どうすれば防ぐことができるのか?について解説していきます。〜システムをきちんと運用するための基礎知識システムは「作って終わり」ではなく,運用の中でさまざまな問題が発生します。問題の発生に備えて事前にどのような対応をしておくべきなのか,問題発生時に何をしなければならないのか,ポイントを解説していきます。きたみりゅうじの聞かせて珍プレーソフトウェア開発の現場で体験したトホホな失敗,思わずうなる珍プレーをきたみりゅうじ氏が四コママンガで紹介。Linuxのメンテナンスの傍ら,Linuxやオープンソースソフトと日々を過ごす著者が,その魅力とつきあい方を,エッセイ風味でお届けします。PRESS特別編集部員,さわやか笑顔のスーパーハカーはまちちゃんとネット大好き14歳わかばちゃんが,毎号,読者の皆さんから寄せられたおたよりを紹介します。皆さんの日頃の悩みにも答えちゃいますよ。]メールでのお知らせメールで次の案内をお送りしております。メールの配信を希望する方は,利用したい項目をチェックしてメールアドレスを入力し,[登録]ボタンをクリックしてください。UPDATES[ほぼ週間に1回]新刊メールマガジン[ほぼ週間に1回]電脳会議の各号案内[ほぼ1ヵ月半に1回]※変更する場合や停止する場合は,登録情報変更ページをご覧ください。※登録いただいたメールアドレスには,そのお知らせ以外,配信いたしません。Ltd.ページ内容の全部あるいは一部を無断で利用することを禁止します。個別にライセンスが設定されている記事等はそのライセンスに従います。