Zenn
📝

AI時代でもドキュメントを理路整然と書くために努力する

に公開
AI
ドキュメント
idea

ドキュメント書いてますか？

AIによってドキュメント（README、手順書、ナレッジ、Tips、オンボーディング資料）がリアルタイムに自動で生成される時代になってきました。ここ最近ではDevin wiki等の超強力なドキュメント生成ツールも登場し、いよいよドキュメントを書く必要性が薄れてきました。

とはいえ、まだドキュメントを書くタイミングは多く「会社独自の審査提出フロー」「会社文化に基づくルール」など、AIでは生成できないものも多く存在するかと思います。また、生成AIの精度もまだまだ完璧ではなく、生成されたドキュメントをそのまま利用することは難しいこともあり、情報源としての利用を考えると、ドキュメントを自分で書く必要性は依然として高いです。

今回はドキュメントを理路整然と書くために努力していることを備忘録も兼ねてまとめます。

順序立てられたフォーマットを利用する

ページ毎に見出しの順番がバラバラだと読み込む際に混乱してしまうことがあります。

そのため、ドキュメントを書く際は以下のような順序立てられたフォーマットを利用するように意識しています。

## Overview
一文でこの資料の概要を説明する

## Goal
この資料を読むことで得られる状態を箇条書きする

## Contents
本題

### Detail 1
### Detail 2

## Related
関連資料や参考文献、Slack等のURL

NotionAI等のAIによるドキュメントの学習観点でも概要を最初に書くことで、内容理解の精度が向上すると言われており、このようなフォーマットで記載するようになりました。

適切な粒度に統一する（ページを分ける）

ドキュメントの内容を適切な粒度に分けることで、情報を探しやすくします。

例えば、会社のCI/CDに関連するドキュメントを作成する場合、以下のように分解してドキュメントを作成しました。

.
└── CICD_Overview/
    ├── CI_Build/
    │   └── CIBuild.md // CIによるビルドに関するドキュメント
    ├── CI_Test/
    │   ├── FullTest/
    │   │   └── FullTest.md // フルテストに関するドキュメント
    │   ├── SelectiveTest/
    │   │   └── SelectiveTest.md // 差分テストに関するドキュメント
    │   └── CITest.md // CIによるテストの概要（フルテスト・差分テストの内容は各詳細ページに記載）
    └── TestFlight/
        └── TestFlight.md // TestFlightに関するドキュメント

このように分けることで、ドキュメントを探す際に「CI_Build」や「CI_Test」などのフォルダを開くだけで、関連するドキュメントを見つけやすくなることや、一つひとつのページがそこまで分量も多くないため、辞書引きのように必要な情報を探しやすくなります。

AIによるレビューを通す

AIも活用してドキュメントの書きやすさと読みやすさを向上させます。

私は普段ドキュメントやブログを書く際にVSCodeを利用しているので、GitHub CopilotやClineというAIプラグインを利用して最終的なアウトプットの品質を担保しています。

Cline Rulesでドキュメントの記載順序やマークダウン記法のルールを定義することや、AIによるレビューを実施しています。ここ最近では以下のようなプロンプトでレビューをしています。

このページをレビューしてください。特に文章の誤字脱字、文末処理の統一、マークダウン記法のルールを守れているかを確認し、問題がある場合は修正してください。

この指示により、今回の投稿では以下のような差分がありました。
-> GitHub - a47506

マークダウンで書く際に意識していること

エンジニアはマークダウン記法が大好きです（たぶん）

マークダウン記法は非常にシンプルで書きやすいですが、Markdownの書き方は人によって異なるため、統一感がなくなってしまうことがあります。そこで、メンテナンスまで意識して以下のようなルールで記載しています。

  • 見出しは「見出し1(#)」から記載する
  • 見出し1(#)、2(##)の場合は、直前に空行を2行入れる
  • 画像サイズは"width=600"で作成する
  • VSCodeに「Markdown All in One」プラグインを入れておく
  • コードブロックはシンタックスハイライトされるように言語を指定する

見出しは「見出し1(#)」から記載する

Zennの記事の場合は見出し2(##)から記載することが推奨されています[1]が、社内で利用するGitHub上のドキュメントの場合は、見出し1(#)から記載することで見出しフォントの大きさが読みやすくなります。

見出し1(#)、2(##)の場合は、直前に空行を2行入れる

直前に空行を2行入れることで、マークダウン（Raw）の状態でも読みやすさが向上します。実際の表示には影響しないため、空白行の行数はお好みで調整可能です。

# Contents
〜〜〜


## Detail 1
〜〜〜

### Some
〜〜〜

画像サイズは"width=600"で作成する

画像サイズは600pxで作成し、できる限り横長になるように作成することで読みやすいです。縦長の画像になる場合は適宜画像サイズの調整や表示領域の調整等を行っています。
※ Zennの記事の場合は 1920pxで作成して領域いっぱいになるように作成しています。

VSCodeに「Markdown All in One」プラグインを入れておく

Markdown All in Oneプラグインを利用することで、VSCode上でMarkdownのプレビューや、テーブル作成時に自動でフォーマットを調整してくれるなど、非常に便利な機能があるため、Markdownを書く際は必ずインストールしておくことをおすすめします。

コードブロックはシンタックスハイライトされるように言語を指定する

意外と忘れがちですが、マークダウンのコードブロックはシンタックスハイライトできる場合が多いです。GitHubの場合は Linguist を利用しています[2]。

以下のように、コードブロックの最初に言語を指定することで、シンタックスハイライトが適用されます。

｀｀｀swift
func hello() {
    print("Hello, world!")
}
｀｀｀

忘れがちですが、可読性が大幅に向上するため、必ず指定するようにしています。

まとめ

簡単ではありますが、以上が私がドキュメントを書く際に意識していることです。

  • フォーマットの統一
  • 粒度の統一
  • AIによるレビュー
  • マークダウン記法

AIによるドキュメントの生成精度が向上しているため、今後いつまで自分で書く必要があるのか懐疑的ですが、今後もドキュメントを書く際はこのようなことを意識して書いていきたいと思います。

脚注

  1. Zenn - ZennのMarkdown記法一覧 ↩︎

  2. GitHub - Creating and highlighting code blocks ↩︎

Discussion