18 Software Documentation Tools that Do The Hard Work For You

🟢ボーナス資料です。 Git Workflow Checklist to simplify & streamline version management

ドキュメントなしでは、ソフトウェアはただのブラックボックスです。 そして、ブラックボックスは、その内部構造がオープンでそれを必要とする人々から隠されているため、ほとんど役に立ちません。

ソフトウェア ドキュメントは、ソフトウェアをガラスの箱に変え、ユーザーや開発者にそれがどのように動作し、使用されるかを説明します。

おそらくドキュメンテーションを見たことがあると思いますが、復習が必要な場合は、Slack の API の例を挙げます:

ご覧のように、Slack はその API に関するすべてを非常に詳細に説明しています。 関連するページはすべてリンクされており、簡単にアクセスできるトピックのサイドバーがあり、ユーザーが見ることができるスクリーンショットがあります。

これをより詳細に説明するために、この Process Street の投稿で次のトピックを取り上げます。

• ソフトウェア ドキュメントとは何か
• ソフトウェア ドキュメントのホスティング オプション
• ソフトウェア ドキュメント用のライティング ツール
• ソフトウェア ドキュメントの最後の言葉

さぁ、はじめましょう。

ソフトウェアのドキュメント化とは何か？

「ソフトウェア工学におけるドキュメント化とは、ソフトウェア製品の開発および使用に関するすべての文書および資料を包括する用語です」 – Prototype.io, Software Documentation Types and Best Practices

すべてのソフトウェアには、製品が何か、それがどう機能し、なぜそのように機能するかを詳細に説明する何らかの形式のドキュメントを持たねばならない。

“If it isn’t documented, it doesn’t exist” – Sitepoint, A Guide to Writing Your First Software Documentation

開発者として、あなたの主な目的は、できる限り最高のコードを記述することです。 自分のコードがクラスで最高で、読みやすく、使いやすく、そして、その結果として素晴らしいことが起こるようにしたいものです。 そうでしょう？

しかし、自分が何をしたのか、なぜそれをしたのかを文書化しなければ、

• 自分以外の誰も自分のコードを使うことができません

文書化しなければ、誰も自分が何をしたのか、なぜそれをしたのかを理解することはできないでしょう。 他の誰かがあなたのコードを拾って作業することは、信じられないほど難しく、不可能に近いでしょう。 場合によっては、あなたが何をしたのか、なぜしたのかを理解しようとするよりも、その方が早く済むかもしれませんから。

• アップデートや改良はできない

3ヶ月前の土曜日の夕食に何を食べたか覚えていますか？ あなたが完全に習慣の生き物でない限り、チャンスはあなたができないことです。 ですから、あなたが書いたコードを、それを実行した 2、3、4 ヶ月後にはおそらく覚えていないと言うのが妥当でしょう。 コーディングの決定の背後にある理由を覚えていない場合、それを更新または改善するのに苦労します。

にもかかわらず、ソフトウェアのドキュメント化は、しばしば急がれたり、ひどく行われたり、優先順位が落ちたり、完全に忘れられたりするタスクです。

ソフトウェアのドキュメントを書くためにどのようなツールを使用できるかの話を始める前に、タスクが最初に行われることを確認する方法を考える必要があります。

プロセス ストリートは、ビジネス プロセス管理 (BPM) ソフトウェアの一部で、プロセスを作成、管理、およびフォローするために使用することができます。

プロセス ストリートが何であるかについては後述しますが、今は、あなたが取り組むすべてのソフトウェア開発プロジェクトにソフトウェア ドキュメントを適合させるためのツールとして、これをどのように使用できるかをお見せしましょう。

以下は、既製のソフトウェア デプロイメント プロセス テンプレートの一例です。 このテンプレートは、ソフトウェア エンジニアやプログラマーが可能な限り最善の方法でソフトウェアをデプロイできるようにするために作成されました。

ここをクリックしてソフトウェア デプロイメント プロセスにアクセス!

このテンプレートを入手するには、ログインしてダッシュボードに追加するか、または無料トライアルにサインアップしてください。

このテンプレートは、新しいコードまたは更新されたコードをデプロイするたびに従うことができるプロセスの完璧な例です。

ステージング環境のセットアップから変更をライブにするまでのデプロイ プロセス全体を通して案内する明確なステップがあります。 これらのステップでは、何も見逃すことなく、プロセス全体が毎回スムーズに進むことを確認できます。

このテンプレートは、貴社に適したデプロイメント プロセスを作成するのに役立つガイドとして使用できるように設計されています。 すべての会社は異なり、すべてのソフトウェア プロジェクトは異なり、すべてのデプロイ プロセスは異なります。

このプロセスを編集し、あなた、あなたの会社、およびあなたのプロジェクトに関連するタスクを追加することができます。

そこで、ソフトウェア ドキュメントに話を戻します。 そうすれば、ソフトウェアの展開プロセスで作業している人は誰でも、プロセスの一部として、これを完了することを思い出し、奨励されるでしょう。

あなたにとって役に立つかもしれない、あらかじめ用意されたプロセス テンプレートがいくつかありますので、この投稿の最後に記載します。

その前に、ソフトウェア ドキュメントをどこに保存するか見てみましょう。

Software Document hosting options

自分のコンピューターにテキスト ファイルの束だけを置いておくのは良くありません。 開発者やユーザーがアクセスできる必要があり、それは 1980 年代ではないので、インターネット上でドキュメントをホストすることによって行う可能性が高いです。

Process Street (社内用)

新しい開発者のトレーニングやドキュメントをすべて同じ場所に保管するには、ソフトウェア ドキュメントのための確固たる選択肢である Process Street を選択します。

まず、ドキュメントを書くためのプロセスを作成し、正しい詳細をすべて把握し、可能な限り有用なものにすることができます。

次に、以下の使いやすい機能を使って、ドキュメントを書き上げ、一箇所に保存することができます。

• 画像ウィジェット
• テキスト ウィジェット
• ビデオ ウィジェット
• ファイル ウィジェット
• サブタスク
• メール ウィジェット
• 埋め込みウィジェット

PROcess Street で文書を保管すると、社内の誰もがアクセスすることができるようになります。 他の人と共有したり、承認のために送信したり、レビューのリマインダーを設定したり、簡単に更新したりすることができます。

文書化できるものは、Process Street で文書化できます。

無料トライアルにお申し込みの上、お試しください。

Read The Docs

Read The Docs が無料で使えることは、できることをすべて見たとき、驚くべきことです。 GitHub と同様に、サイトにオープンにインデックスされるオープンソースの資料を好きなだけ作成できますが、ドキュメントを非公開にして社内で使用したい場合は費用がかかります。 5087>

Read The Docs が優れている理由は、Git、Mercurial、Subversion、および Bazaar を含む任意のバージョン管理システムからドキュメントを簡単にインポートできることです。

Getting Started ガイドをチェックして、どのように動作するか、また、そこでホストされたときにドキュメントがどのように動作するかを感じてください。

GitHub (& GitHub Pages)

自分のソフトウェアのバージョン管理をするために GitHub を使用しているなら、最低限リポジトリ内に README.MD ファイルを持っていることでしょう。 過去に何百万人もの人が行ってきたように、GitHub をソフトウェアの文書化に使用するには、その README をマークダウンで埋めるだけです。

素晴らしい例は sferik の t リポジトリで、スクリーンショットはこちら：

フォーマットされたテキストの 1 シートだけでは不十分な場合は、GitHub の Pages ツール (GitHub アカウントごとに無料の Web ページとホスティングが付属し、独自のドメインもルート可能) を活用することができます。 5087>

上記は、GitHub でホストされている Electron 用の atom.io のドキュメントです。 他のソフトウェアと同様に GitHub のバージョン コントロールと自動的に連動するため、賢い選択と言えます。 このサイトのリポジトリはこちら。

Dropbox Paper（社内用）

社内のソフトウェア ドキュメントの使用については、Dropbox Paper は優れた選択肢です。 前身の Hackpad と同様に、従業員用のプライベートな wiki を作成するために使用できます。 ドキュメントを互いにリンクしたり、コード ブロック、画像、およびページ ジャンプを挿入したり、他のドキュメント ツールに要求されるのと同じです。 全体として、これは社内でドキュメントを開発および作成するための素晴らしいツールで、おそらく後で公開することを視野に入れたり、社内で使用するためだけのものです。

Atlassian REST API Browser (API 使用)

アトランティスの REST API ブラウザ (RAB) は JIRA Server, Confluence Server および Stash インスタンスにデフォルトとして含まれています。 これは JIRA/Confluence 環境で使用可能な API を発見するために構築されており、またあなたのドキュメントをホストする場所でもあります。 5087>

JIRA/Confluence 互換 API をより多く公開するために、このツールを使って API を文書化しましょう。 5087>

Tettra (社内用)

Tettra は知識ベースソフトウェアの一種で、開発やあらゆることを文書化することができます。 日常的には、すべてのプロセスを文書化した単一の場所を持つために Tettra を使用しており、1 つのプロセスが他のプロセスとどのように関連しているか、または私たちが構築したさまざまな自動化がどのようにセットアップされているかを忘れることはありません。 つまり、ソフトウェアのドキュメントや、会社の内部 Wiki としても最適です。

Tettraは特に知識管理のために設計されているため、他のサポート機能も多数搭載されています。 たとえば、組織の全体像や物事がどのように組み合わされているかを示すために、追加したいコンテンツやセクションを提案することが可能です。

開発チームがどのように Tettra を使用するか、ここで少しビデオを見ることができます。

また、Process Street と共に Tettra をどのように使用しているかについては、こちらを参照してください。 ワークフローとチェックリストの自動化。

チェックしてみてください！

養蜂場 (API 使用)

養蜂場は、蜂が生息する場所であると同時に、 API ドキュメントのための専用ホストでもあります。 マークダウンで書き、モック API コールを追加すると、Apiary はそれを以下のようなものに照合します:

誰でも、アプリに入ったり実際に呼び出しをプログラムしたりせずに API をテストできるので、あなたの API を共有する、それを詳細に記録し、それができることを誇示する非常にアクセスしやすい方法となります。

ソフトウェアのドキュメントをどこに保存するかについて説明しましたが、今度はそれをどのように書くかについて見てみましょう。

Writing tools for software documentation

ソフトウェア ドキュメントは、バージョン管理でコード ファイルと共存できるようにプレーン テキストを維持しながら、ハイパーリンクとフォーマットできるように、しばしばマークダウンで記述されます。 つまり、執筆ツールの多くは、執筆体験を楽しくしてくれるシンプルなマークダウン エディタを選択します。 さらに、非常に効果的な非マークダウン ソリューションもいくつかあります。

MarkdownPad (Windows)

無料版とプレミアム版があり、どちらも素晴らしい機能をたくさん備えています。 5087>

MarkdownPad は無料で入手でき、プレミアム版は 14.95 ドルです。

iA Writer (Mac)

iA Writer はシンプルで美しいマークダウン エディタで、ライブラリ機能によりサイドバーで他のドキュメントを簡単に参照することができます。 ソフトウェア ドキュメントで期待されるようなドキュメント間の内部リンクはありませんが、最終的な形 (つまり、インターネット上のサイトに掲載される場合) になれば、いつでもそれらをパスすることができます。

iA Writer は Mac App Store で 9.99 ドルです。

Profs Knowledge Base

Profs Knowledge Base は、文書作成と編集からカスタマイズ、ワークフローの設定、そして公開に至るまで、あらゆる段階で使用できる素晴らしい小さなツールです。 マルチメディアを追加したり、Word文書、PDF、またはPPTから既存のコンテンツをインポートしたり、文書の複数のバージョンを保存し、必要なときにそれらを復元することができます。

しかし、このツールの本当の素晴らしさは、その使いやすさにあるのです。 誰でも、そして誰もが、ソフトウェアのドキュメントを構築するために使用することができます。 5087>

Profs は無料で使用できますが、月額 112 ドルのプレミアム パッケージにアップグレードすることもできます。

SimpleMDE (ブラウザ)

マークダウンは、厳密には「ツール」ではなくプレーンテキストをフォーマットする方法なので、どのテキスト エディタでも技術的に記述できますが、ブラウザ上でも可能なことは驚くことではないでしょう ! SimpleMDE は JavaScript で構築された機能的なマークダウン エディターであると同時に、オープンソースのプロジェクトであり、そこから学び、必要に応じて自分自身の用途に合わせることができます。 5087>

reStructuredText editor

Markdown はソフトウェアのドキュメントを書くために最もよく使われる 2 つの言語のうちの 1 つですが、これまで見てこなかったもう 1 つの言語があります。 これは markdown に非常に似ていますが、ソフトウェアドキュメンテーションの目的のために学ぶ価値があります。

reStructuredText の作成者である Docutils は、ここに reStructuredText エディタのリストをまとめています。

reStructuredTextは簡単に異なるフォーマット間でコンバートできる点がポイントです。 特にプレーンテキストから静的なWebサイトへ。 詳細はこちらをご覧ください。

Tools to automatically generate documentation from source code

There’s nothing like the human touch when it comes to the documentation (it is clear in the docs of Slack and Giphy, to the couple name of the couple). しかし、出発点として (特に巨大なソース ライブラリの場合)、骨格となるドキュメントを自動的に生成することが最善です。 これは、ソースの関数やコメントを解析して行う作業で、言語によっていくつかのオプションがあります。

自動生成だけに頼る前に、この StackExchange のスレッドを読んで、長所と短所を比較検討することをお勧めします。

ソフトウェア ドキュメントに関する最後の言葉

派手なソリューションやクイック フィックス、ほとんど同じツールがたくさんあります (まったく正直なところ)。 何が最終的に重要かというと

最終的に最も重要なのは、そのことです。

a) 構築するソフトウェアごとにソフトウェア ドキュメントを書くこと
b) 包括的に書き、ユーザーがアクセスできる場所にホストすること

先に、開発プロセスのテンプレートをいくつか持っていると言いましたが、チェックしてみたいと思われるでしょうか。

では、これらを紹介しましょう。

Process Street 開発プロセス テンプレート

これらのテンプレートを提供する前に、Process Street とは何かをもう少し説明しましょう。

つまり、Process Street は超強力なチェックリストであることがわかりました。 これは、プロセスの作成と管理を支援するソフトウェアの一部です。

でも待ってください、Process Streetはそれだけではありません!

このイントロビデオを見て、私が言いたいことを確認してください。

つまり、開発プロセスのテンプレートを作成し、開発プロセスを完了する必要があるたびに、このテンプレートを使って個々のチェックリストを実行できるだけではありません。 5087>

• タスクの停止
• 動的な期限
• タスクの許可
• 条件ロジック
• 承認タスク
• 埋め込みウィジェット
• 役割割り当て

タスクを割り当てることができる。 また、Zapier、Webhooks、または API 統合により、このプロセスを何千ものアプリケーションに接続することができます。

このウェビナーでは、当社の最新機能を紹介し、それらを最大限に活用する方法について説明します。

これらのことを念頭に置いて、以下の既製のテンプレートをご覧ください:

ネットワーク セキュリティ監査チェックリスト

このテンプレートは、リスク マネージャーまたは同等の IT 専門家がネットワークのセキュリティ脆弱性を評価するために使用できます。

月例 Web サイト メンテナンス チェックリスト

この月例 Web サイト メンテナンス チェックリストを使用して、サイトの読み込み速度を最適化し、脆弱性をスキャンし、検索の可視性を見直します。

月例 Web サイト メンテナンス チェックリストにアクセスするには、ここをクリック！

ソフトウェア テスト チュートリアル

設計、クライアント処理、および起動後のチェックを含むソフトウェア開発プロジェクトの開始から終了までの全体管理にこのプロセスを利用することができます。

ソフトウェア テスト チュートリアルにアクセスするには、ここをクリックしてください！

以上で、あなたの生活を楽にするものを自由に使うことができます。 このリストの中から、新しいお気に入りのツールが見つかることを願っています。