📝

アジャイルなノートの書き方入門〜構造化ドキュメンテーション

2023/09/11に公開

Git

2024-07-20 更新: 空行とアンダースコアにリンクを追加
2023-11-13 更新: パンくずリストと同様の区切り記号 >> について追加。書きかけを表す空行とアンダースコアについて追加
第2回: アジャイルに手順書を書くための 13のルール

Note as Code：簡単に編集ができるアジャイルなノートを書こう

「アジャイルソフトウェア開発宣言」には、「包括的なドキュメントよりも動くソフトウェアを」と書いてあります。

「コードをきちんと書けばドキュメントは要らない」とよく言われますが、そうは書いていません。ドキュメントは必要です。しかし、「包括的な」ドキュメントと書かれているので、あらゆるものをドキュメントにすべきというわけではないのでしょう。コードとドキュメントのうち、それぞれが表現できることが得意なほうを選んで書く、どちらでも良いのならコードを優先する、という程度の理解を私はしています。しかし、コードとドキュメントの2択で十分でしょうか。

ドキュメントは自然言語や図表などあらゆる手段を使うことができるのでコードでは表現できないあらゆることを表現できると考えられていますが、図表の作成コストがかかりすぎますし、ダイナミックに表示内容を適切な形に変えることはありません（普通、動画は作りません）。あくまで紙の表現を電子化しただけです。また、大部分を占める本文自体の階層構造は文の中に隠れてしまっています（具体的には後述します）。

一方、コード（プログラミング言語やマークアップ言語）はインデントを使って階層構造を視覚的に表現できます。クラスとメソッド、定義済みのデータ構造、テスト項目などを表現できます。そこまでは大丈夫です。しかし、それらが膨大になったとき必要とされる概要的な階層構造や、導出される階層構造（コールツリーなど）や、コーティング前のドメイン（ドメイン駆動設計）の階層構造はコードに表われているわけではありません。

つまり、ドキュメントとコードだけでは表現できない設計上の表現があるのです。ここではそれをノートと呼ぶことにします（なお、動画などは設計上のドキュメントではなくプロダクトなのでノートの対象外とします）。

これから数回に分けて構造化ドキュメンテーションの書き方について説明します。この書き方を流行りに乗った言葉で言えば Note as Code (NaC) でしょうか。Markdown や Mermaid のように既存のドキュメントをコードで書く（Document as Code?）ではなく、コードのコメントを集めることでもなく、ドキュメントを Git で管理（Docs as Code?）はするのですが、ドキュメントとコードだけでは表現してこなかった情報を、より適切な形でかつ簡単に表現するのです。またテキストエディターで編集でき、Mermaid と違って編集結果がそのまま見えるという特性は、アジャイルな特性です。構造化ドキュメンテーションをマスターしてノートを書くと、概念や情報の理解が早くなり記憶の定着もしやすくなります。

私がプログラミングするときは、ノートを読み書きする時間が全体の半分近くを占めます。仮想デスクトップの左半分にノートを置き、右半分に統合開発環境などを置いて、マウスの中クリックでパタパタ切り替えています。

なお、UML には様々な種類の図があるように、構造化ドキュメンテーションにも様々な種類の様式があります。

見出し：見出しのツリーを作り、折り畳んでから選ぶ

一般の文書では、見出しに編・部・章・節・項といった名が付けられる慣習があり、階層構造になっています。

ちなみに法文では階層構造に、章・節・条・（数字）・（漢数字）・（イロハ）が付けられます。法文サンプル（e-Gov）

章
    節
        第一条
            （数字）
                （漢数字）
                    （イロハ）
        第二条
            ...

こういった階層構造は、概念を理解する上で非常に役にたつ情報です。なので階層構造はもっと大いに活用すべきです。

Visual Studio Code では、Ctrl + ( K, 0 ) と押す、つまり、Ctrl キー（mac は command キー）を押しながら K, そのまま Ctrl キーを離さずに 0（ゼロ）と押すと、すべて折りたたんで PCのフォルダーのようにトップの直下だけを並べることができます。その状態で行番号の右の三角をクリックすると 1段深い見出しが見えます。さらにクリックするともっと深い見出しが見えます。エクスプローラーの左半分にあるツリーと同じですね。

→

→

→

Shift キーを押しながら三角をクリックすると最も深い位置の値まで開きます。ある程度の深さまで開いたら最も深い位置まで一気に開いて見渡したほうが目的の情報が見つけやすいでしょう。もう一度同じ三角を Shift キーを押しながらクリックすると直下の見出しだけになり、それより深い見出しや値は閉じられます。Ctrl + ( K, J ) と押すとすべて開きます。Ctrl + ( K, - ) と押すと今カーソルがあるところだけ開いた状態になるように外側をすべて閉じます。

キー	動作
Ctrl + ( K, 0 )	すべて閉じる
Ctrl + ( K, [ )	深くまですべて閉じる
Ctrl + ( K, - )	外側をすべて閉じる
Ctrl + ( K, J, K, 2 )	すべてを深さ＝２にする（開くまたは閉じる）
クリック	1つ開く
Shift + クリック	深く開く、または直下だけにする、または深くまですべて閉じる
Ctrl + ( K, ] )	深く開く
Ctrl + ( K, J )	すべて開く

※ 現在位置から+2深いノードまで展開することはできません。拡張機能を開発すれば作れるかもしれませんが。

こういったフォルダーを選ぶような探し方が細かいレベルまでできるのが構造化ドキュメンテーションの特長です。単語がうろ覚えでも連想して目的の情報までたどり着くことができます。

一般の文章では全てが開いた階層構造しか見えませんが、全てを折り畳んで見渡すことで全体像を把握でき、記憶できるようになります。

一方、ドキュメントを書くとき、階層のレベルを深くまたは浅くするのはとても簡単です。Visual Studio Code の場合、行番号をクリックまたはドラッグして、タブキーを押すと 1段深くできます。Shift を押しながらタブキーを押すと 1段浅くできます。

→

余談ですが、インデントを深くすると上記のようにエラーが赤い波線で表示されてしまいます。エラーの内容は赤い波線にマウスを合わせると表示されます。表示されるエラーは「All mapping items must start at the same column」です。インデントの位置がおかしいよというエラーです。細かく言うと、インデントの深さが深くなった最初の行のインデントの深さに後のインデントは合わせる必要があるのです。つまり、「第一章」のインデントの深さが正しい深さの位置とされ、それより浅い深さにある「第二章」は位置が間違えていると判断されてしまったからです。（「第二章」がある場所ではなく、その前の行にエラーがあるのが分かりにくいですが）

深い要素が1つしかないときは、パンくずリストと同様に >> で区切って書けば、1行で深い部分を表すこともできます。

第一部 >> 第一章 >> 節1:
第二部:

上記は下記と同じ構造を表します。

第一部:
    第一章:
        節1:
第二部:

特長： YAML 形式と typrm タグを使うメリット

構造化ドキュメンテーションの物理的な形式は YAML です。YAML はデータをツリー状に記述できるテキスト形式のファイルタイプの 1つです。プログラミング的にいえばオブジェクトをネストして記述できるファイルです。YAML の概要や詳細はネットを検索してみてください。

ノートがテキスト形式であることで次の特長が得られます。

高速な検索
Git を使ったバージョン管理、デバイス間共有、マージ
どこでも内容を表示・編集できる
URL からブラウザーやアプリを開く（自動でリンクが付く）

ノートが YAML 形式であることで次の特長が得られます。

ツリーの折り畳み
項目名と値の色分け、体系的な概念を視覚的に理解できる
重複した項目の自動チェック
永続的な利用とAI等の活用（グローバルに普及していることのメリット）

さらに typrm のタグをノートに付ければ次の特長が得られます。
なお、typrm は独自に開発中のツールのことで、タグを処理します。
GitHub で公開されています。

精度の高い検索、シソーラスを使った複合検索
スニペットの即時表示、注目すべき部分の表示（フォーカス）
テキストファイルの中の注目すべき行へのジャンプ
覚えるべきキーワードの提示
どのデバイスでも変わらないファイルパス
変数を使った内容の置き換え

これらのメリットが具体的にどういったものなのかはこれから説明していきます。

サンプル

構造化ドキュメンテーションで書かれた簡単なサンプルを示します。これに近いものならメール等に書いたことがあると思います。

8周年ライブ:
    日時: 9月9日 17:00
    場所: 名古屋

もう少し実践的なノートとしては、エクセルの使い方でしょうか。このノートには文字に色がついていませんがリンク先の全体には色が付いているので見やすいです。全体はこちら。

...
    日時: #keyword: Excel 日時
        日付: #keyword: Excel 日付
            入力:
                セルに入力するときは、[ 2005/3/4 ]、[ 4/5 ] のように入力します。
                式に入力するときは、 DATE(2005,3,4) のように入力します。
            今日の日付: |  #// 自動的に更新されないようにする場合
                [Ctrl]+[;]
        時間: #keyword: Excel 時間
            入力:
                セルに入力するときは、[ 12:00 ]、[ 12:00:00 ] のように入力します。
                式に入力するときは、 TIME(12,0,0) のように入力します。
            現在の時刻: |  #// 自動的に更新されないようにする場合
                [Ctrl]+[:]
            24時間越え表示: |  #// 時間を合計するなどして 24時間を超える値が入るはずなのに少なく表示されてしまう場合
                セルの書式設定 >> ユーザー定義 >> [h]:mm
            マイナス表示:
                =TEXT(ABS(B2-A2),IF(B2<A2,"-h:mm:ss","h:mm:ss"))
            計算:
                差分から１時間減らす:
                    =B1-A1-TIME(1,0,0)
        関数:
            NETWORKDAYS: #keyword: Excel NETWORKDAYS,  Excel 稼働日数 祝日 稼働日判定
            ...

初めて見たときは複雑に見えると思いますが、階層化されている項目名（コロンの左の数文字）だけを斜め読みするだけでどういったことが書かれているかが分かってくると思います。このように体系的に整理されているので目的の情報へたどり着きやすくなっています。

ニュースなどの情報収集にもノートを使っています。私は収集した情報を忘れないためにニュースのブログを書いているのですが、その記事を書くためのノートを構造化ドキュメンテーションで書いています。全体はこちら。

プロンプト: 下のメモを元にクールに紹介するブログの文章を作ってください。
概要: 2023年 6月 6日、アップルが開発者会議 WWDC 2023 にて Apple Vision Pro を発表
空間コンピューティング: #keyword:
    パススルー:
        パススルー機能: #keyword:
            自分がいる部屋がみえる。安全に家の中を歩き回れるビデオシースルーAR。
            Vision Proが生成している画像。周囲が透けて見えているわけではない。
            複数のパススルーカメラを用いて周辺環境を取り込みます。
            それでも時々かなり強い圧縮が見られ、人の顔が影に移動するとディテールが失われることもありました。
        Hololens との比較:
            Hololens は色のフリンジとして感じられることもある。実景と重ねる関係から、完全な黒は出しにくい。
            Apple Vision Pro ではこの問題はないだろう。
        ウィンドウ:
            空間にアプリや3Dオブジェクトを自由に配置。
            顔の向きを変えて広く空間を使える
        ...

最近の私のブログはこういったメモを AI に入力して生成した記事を上げています。おそらく AI はインデントで表現される関係を理解しているのではないでしょうか。

環境：構造化ドキュメンテーションを書く環境を整える

構造化ドキュメンテーションを書く前に、まずは YAML の文法を自動チェックする環境を整えましょう。自動チェックで警告されることで構造化された文章を書くことを意識するようになります。最近のプログラミング用のテキストエディターならだいたい YAML の文法チェックに対応していると思います。

Visual Studio Code をインストールして YAML の編集環境をセットアップする方法を説明します。

Visual Studio Code をインストールします。https://code.visualstudio.com/
をブラウザーで開き、ダウンロードして、実行します。インストールオプションはすべてデフォルトで構いません。

インストールが完了したら、Windows なら Visual Studio Code を起動してタスクバーを右クリックして「タスクバーにピン止め」してください。mac なら Dock に配置してください。後ですぐにメモできるようにするためです。ピン止めをしないのは、しばらく使ってみたけど結局あまり使わなかったと自覚したときでも遅くありません。

Visual Studio Code でドキュメントフォルダーを開きます。ファイルメニュー >> フォルダーを開く >> ドキュメントフォルダー。

新しい YAML ファイルを作ります。エクスプローラービュー >> DOCUMENTS（にマウスを合わせ）>> 新規ファイル（最も左のボタン）>> note.yaml >>（Enter キー）

ファイルのインデント（行頭から始まる空白の並び）を 4つの空白に設定します。ダミーの文章を下記のように入力し、一度 note.yaml を閉じて note.yaml を開き直してください。そして、数行でもインデントかある文章が書けたらダミーの文章は削除してください。厳密には設定ではなく Visual Studio Code がインデントが 4つの空白であると自動判定されるようにファイルを作り始めます。インデントがある内容が全くないとインデントは 2つの空白であると Visual Studio Code が判断してしまい、見にくくなってしまいます。

0:
    4:

基本：初めての構造化ドキュメンテーション

まずは簡単な情報を構造化してみましょう。安心してください。おそらくあなたも以前書いた経験があると思います。

「次の周年ライブは9月9日17:00から名古屋で開催されます。」この文章を構造化すると次のようになります。

8周年ライブ:
    日時: 9月9日 17:00
    場所: 名古屋

項目名の右には必ずコロンを書いてください。「日時」と「場所」はインデントされています。「周年ライブ」が親、「日時」と「場所」が子という構造になっています。
このような書き方は、事務職の方なら会議のお知らせを書くときに経験していると思います。

なぜこのように書くのでしょうか。それは文章を読まなくても、ぱっと見ただけで日時または場所が分かり、頭に入りやすいからです。

項目名：項目名を書くと読まなくても単語で探せるようになる

構造化ドキュメンテーションのポイントは項目名を明示的に書くことです。元の文章には「日時」「場所」の単語はありませんが、これを明示的に書くことです。こうすることで、文章の構造を読まなくても情報を知ることができるようになります。

項目名が書かれていないと YAML の文法チェックがエラーを表示します。ですので是非ともエディターをインストールして項目を書くクセを付けてください。

項目名が思いつかないときは、とりあえず主語を項目名として独立させるとよいでしょう。たとえば、

「好きなポケモンはイーブイです。」

好きなポケモン: イーブイ

「うまくいかないときは何もしないでおこう。」

うまくいかないとき: 何もしないでおく

「象は鼻が長い」

象: 鼻が長い

象の鼻: 長い

象:
    鼻: 長い

最後は 3種類のサンプルを示しましたが、どれか1つが正解というわけではありません。プログラムが値を参照するわけではないのでどれでも構いません。ちなみに「象は鼻が長い｣という文章は二重主語問題のサンプルとしてよく知られている文章です。どれが主語でどんな意味なのかが専門家でも議論が分かれる文章として有名です。なので、まず大事なのは項目の質よりも項目を書くことです。とはいえ「長い」を項目名にするのは悪すぎますね。ヨーダ記法がいかに混乱の元になるのかがよく分かります。（左に定数があることではなく==が書かれていることをチェックしろ！）

YAML では重複する項目名を書くと警告されます。どうしても書き分けられないときは、番号をつけましょう。

手順: ...
説明: ...
手順 (2): ...

どうしても良い項目名が思いつかないときは、_ （アンダーバーだけ）の項目名を書いておきましよう。_ は Go や Swift などのプログラミング言語において省略を表す書き方として知られています。

_: 象は鼻が長い

アンダーバーが嫌ならコメントにします。

#// 象は鼻が長い

列挙するときは行頭に数字やアルファベットを項目名にします。

1: 1つ目の値
2: 2つ目の値
3: 3つ目の値
4:
    項目名: 値
    項目名2: 値
a: 値
b: 値

それも嫌なら、ハイフンを付けます。ただし、上下の隣に項目を書くことができなくなります。ハイフンの右なら項目を書くこともできます。タブ幅が 4 のときはハイフンの右の空白は 3つ（タブ幅 - 1）になります。

列挙のサンプル:
    -   項目名とコロンの代わりにハイフンを付けて値を列挙します
    -   2つ目の値
    -   3つ目の値
    -   項目名: を付けることもできます  #// YAML 的には [0]〜[2] が文字列, [3] が属性が 1つのオブジェクトになります。

複数行の値： YAML の文法を無視するブロックにはバーティカルライン (|)

1行の中にコロン（と空白）が複数入っていると YAML では文法エラーになってしまいます。他にも様々な YAML の文法エラーに対処する必要があるのですが、YAML の文法を1つ1つ理解する必要はありません。下記の2つだけ覚えれば殆どのエラーは回避できます。

| を付けて、次の行からインデントを深い部分を全て値として扱うようにします。

memo: |
    昨日: 〇〇様:
    例の件はいかがなさいますか。

| がよく使われるのは、書きかけの内容や、プログラムのコードのサンプルや、文章の引用などです。まだ書く内容が整理されていないときは YAML の文法チェックが煩わしく感じるでしょうが、| を書くだけでエラーが消え、書くことに集中できます。ただし、文法的には全て値になるため、色分けはされなくなります。

"',&%@[{* などから始まる値はエラーになってしまうでしょう。通常の値ではなく YAML の特殊記号として扱われてしまうからです。それ以外の文字から始まるようにたとえば () で囲むと、エラーは解消されます。

(&): And

早く探す：早く選べるように見出しを短くして概要を書く

見出しから目的の情報を選んで探せるようになっても、ある程度は見出しを読まなければ選びようがありません。分かりやすく説明するために丁寧に見出しを書く人は多いと思いますが、長すぎると逆に不親切です。

これは見出しを長く書いてしまったときの様子です。

スタッシュ:
    編集内容をスタッシュに入れ、編集前（クリーン状態）に戻します:
        名前あり: git stash save __Name__
        名前なし: git stash
    最近プッシュした編集内容が ワーキング フォルダー に復活します: git stash pop
    スタッシュに入っている編集内容（エントリー）の名前を一覧します: git stash list
    編集内容（エントリー）をスタッシュから削除します:
        git stash list
        git stash clear

長い見出しを読まないと、どこの見出しの中を読めばいいか選べませんね。

一方、見出しを短く書いたときの様子です。

スタッシュ:
    プッシュ:
        名前あり: git stash save __Name__
        名前なし: git stash
    ポップ: git stash pop
    一覧: git stash list
    削除:
        git stash list
        git stash clear

読む量は減りましたね。

しかし、何が書いているのか分かりにくくなってしまいました。初めてまたは久しぶりに見たらプッシュ（2行目）は何？となるでしょう。これが、独自の略語だけの見出しだったら最悪です。たとえば X（旧Twitter）という名前や、Linux の man コマンドで表示されるオプション名（が項目名になっているもの）がそうですね。

そこで、分かりにくそうな見出しについては概要もコメントに書くようにします。

見出し:  #// 概要

見出し＋概要という構造が明示的に書かれていることで、

まず短い見出しを早く斜め読みして、分かればすぐ選ぶ
近そうな見出しのコメントをいくつか読んで選ぶ
全てのコメントや内容を読んで選ぶ

という段階が踏めるようになり、早さと確実さを両立させることができます。

スタッシュ:
    プッシュ:  #// 編集内容をスタッシュに入れ、編集前（クリーン状態）に戻します
        名前あり: git stash save __Name__
        名前なし: git stash
    ポップ: git stash pop  #// 最近プッシュした編集内容が ワーキング フォルダー に復活します
    一覧: git stash list  #// スタッシュに入っている編集内容（エントリー）の名前を一覧します
    削除:  #// 編集内容（エントリー）をスタッシュから削除します
        git stash list
        git stash clear

また、記憶すべき単語が短い見出しにありつつ概要を読むので、自然に単語の意味を再学習する形になっています。読むだけで自然に記憶されます。なので、見出しを書くときは正しい用語であるかきちんと調べましょう。

ちなみに # という記号についてですが、# は YAML では、コメントの記号です。しかし　# はコメント以外に Markdown の見出しだったり、プリプロセッサー（#inlucdeなど）の先頭だったり、root のプロンプト # だったりと非常に多くの意味で使われているため、# がコメントであることが分かりにくいという問題があります。そこで私は多くのプログラミング言語で常にコメントとして扱われる // を含んだ #// を書くようにしています。

また、通常、探す基準（視点）はいくつかあるので、なるべく多くの基準でツリーを書きます。たとえば上記は機能別のツリーですが、下記はコマンド名の ABC 順のツリーです。他にもよく使う順もあります。リリース順もあります。どちらが優れているというものではありません。どちらからでも辿れるようにするのです。始めは信じられないかもしれませんが、本当にどちらからも辿ります。ただ、いきなり多くの基準のツリーを網羅して書くのは非効率です。必要になってからツリーや項目を追加するで構いません。

git stash:
    git stash: 編集内容をスタッシュに入れ、編集前（クリーン状態）に戻します  #search: git stash 機能
    git stash clear: 編集内容（エントリー）をスタッシュから削除します
    git stash list: スタッシュに入っている編集内容（エントリー）の名前を一覧します
    git stash pop: 最近プッシュした編集内容が ワーキング フォルダー に復活します
    git stash save: （git stash と同じ）

それぞれの基準のツリーの中に、同じ内容を書きたくなければ、typrm の検索機能（#keyword: と #search:）を使ったリンク関係を書くとよいでしょう。DRY原則を満たせます（やりすぎに注意）。その詳しい説明は別の機会にしたいと思います。

また、見出しはなるべく標準化しておくと選びやすくなります。IT の使い方やプログラミングに関するドキュメントであれば下記の項目の並びの一部をそのまま使うのが良いでしょう。その詳しい説明は別の機会にしたいと思います。

概要:
手順:
画面:
コマンド:
API:
概念:
ログ:
ファイル:
コード:
テスト:
トラブルシューティング:

フォーカス：注目すべき場所を強調表示する

コーディングに使うエディターは、名前をクリックすると同じ名前をすべて強調表示する機能があります。この機能を応用することで、ノートの中で注目したい場所を示すことができます。

読む人に注目させたい場所にある名前を typrm の #focus: タグに書きます。 #focus: タグを書く場所はタイトルの近くなど上のほうに書きます。

読むときは #focus: タグを見つけたら、そこにある名前をクリックまたはダブルクリックまたはフレーズの範囲を選択すると、近くの同じ名前が強調表示され、そこに目線が自然と行きます（Visual Studio Code などで表示するときは #focus: タグがなくても強調表示はされます）。まずそこを読めば内容が理解しやすいでしょう。たとえば、Go言語の Hello, world のサンプルコードを見てみましょう。

何も強調されていないと読者は先頭から読んでいくでしょう。そして package や import は何だろうと調べることになり、調べても処理内容と直接関係ない意味を読まされるので訳が分からなくなり挫折してしまうと思います。最初に読むべき場所は表示を行う Println です。

Println の引数には Hello, world と書いてあるので、表示させるときはこうコーティングするのかと納得できたと思います。（この文章を書くときは、#focus: タグを適切に書いて読者に分かるようにしてください。）

しかし、Println だけ書いても Go 言語のコードは動かないので、次に、import を書かなければ使えないと説明されるでしょう。そこで #focus: fmt を見つけたら fmt をクリックします。

サンプルコードの中の 2箇所の fmt が強調表示されましたね。その表示から import "fmt" の fmt と fmt.Println の fmt の繋がりが見えてくるでしょう。つまり、Println メソッドは fmt パッケージに定義されているメソッドだと分かります。

コピペ：コマンドをキーボードで入力するのは時代遅れ

仮想デスクトップの左半分に「今していること」のノートや資料を置き、右半分に統合開発環境などを置いて、マウスの中クリックでパタパタ切り替えられるようにしていれば、

ノートや資料からコマンドやデータなどをコピー
マウスの中ボタン（仮想デスクトップの切り替え）
統合開発環境に貼り付け

という一連の操作がマウスを殆ど動かさずにできるようになります。もちろん逆方向のコピペもできます。

普通、サンプルに書かれたコマンドはパラメーターを編集してから実行します。しかし、
typrm の #template: タグを使うと、コマンドのパラメーターを自動的に正しく置き換えるので、そのままコピペして実行することができます。正しいパラメーターを指定するには10秒〜数分かかるでしょうから、圧倒的に作業が早くなります。

インデントを浅くするときは、indenter を使うと便利です。（いつかインデントを浅くする VSCode の拡張機能を作るかもしれません）

キーワード検索

ツリーをたどっていけるようになっていても、文書が多くなると目的の情報が書かれた見出しに辿り着くまでが大変になります。そこで検索機能を使います。Visual Studio Code の全文検索機能を使うのであれば、Search ビュー（左上2番目の虫眼鏡をクリック）にキーワードを入力します。

しかし、全文検索機能を使って複数の単語を検索すると、単語の順番が合っていないとヒットしないですし、見出しやキーワード以外の本文にもヒットしてしまうため、検索して見つかった部分が期待と違うことがよくあります。それを回避する方法の 1つが typrm の #keyword: タグです。タグをつけることでそのタグがある場所が優先的に表示されます。

チケット：迷子にならないように今を書き、後でやることはメモする

ネットを検索して見つかった文章を読んでいたら一部の単語の意味がわからなくて、改めてその単語を検索することがあるでしょう。そうなると元々何を探していたか忘れてしまい迷子になることがよくあると思います。興味が移ってしまうこともありますし、分からないことをすべて解決しようとすることもあり、その度に元々何を調べていたのか忘れてしまうことがよくあると思います。

そういった迷える現象を避けるには、今していることが何であるかを明示することです。今すべきことをすぐ見えるようにして寄り道せず集中して早く終わらせるのです。そうしないと、いろいろな新聞を読んで仕事に関係ない記事を読んだとしても情報収集した気になっている使えない人と同じです。

また、突然他のやるべきことを思いついたまたは思い出したときは、やることをすぐにスタックにメモして忘れないようにすることはとても大事です。

そこで編集環境に必要なことは、今していることやスタックが書かれている場所を探さなくて済むようにウィンドウを配置することです。迷子になってもすぐに見える位置に配置することです。たとえば、デスクトップの左半分は「今していることやスタック」の構造化ドキュメントを専用で配置し、右半分は「構造化ドキュメントの資料とその検索」や PDF などを開いたウィンドウを配置します。1つのウィンドウに複数のファイルを開くことができても、ウィンドウを分けるのです。こうすることで、今していることやスタックは常に画面の左に存在させることができます。ファイルのタブを探すようでは良くありません。

今していることやスタックは GitHub Issue などのチケットを単位にします。その詳しい説明は別の機会にしたいと思います。

書きかけ：空行とアンダースコア

構造化ドキュメンテーションを書いている途中で、別のページを見るなどしてから戻るとき、どこを書いていたのか探すことがよく起きます。

空行を入れることで、書いている途中の場所がすぐに分かるようになります。行全体が空いている場所は見つけやすいですし、空いている場所があると埋めたくなるという心理を利用しています。今、書いている場所はここですよと目立つように何かを書く必要はありません。Enter キーを押すだけで空行ができます。何行入れても構いません。一般的な文書では空行はブロックの区切りを表しますが、YAML 形式はインデントでブロックを表現して空行が無くなるので、書きかけを表す空行は見つけやすいのです。

タスクA:
    今までやったこと:
    今やっていること:


    次にやること:
    その次にやること:
タスクB:
    ...

文中に書きかけがある場合、アンダースコアを書いておきます。テストの穴埋め問題ではよくアンダーラインが書いてありますがそれをイメージしています。アンダースコア以外の書き方よりも区別しやすいです。

今ここを書いている途中で、____ が必要です。

ユーザーが入力しなければならない部分（プレースホルダーと呼びます）については、Pascal ケース（単語の始まりは大文字でそれ以外は小文字）でシンボルを書き、その両端にアンダースコアを 2つずつ書きます。文書としては書き終えていても、ユーザーにとっては書き終えていない状態を表します。また、シンボルによって何を書くべきかのヒントになります。シンボルだけで不十分なときは、シンボルの説明を文書に書いておくとよいでしょう。Python 言語の __init__ などの特殊なメソッドなどに似た書き方ですが Python ではシンボルをスネークケース（すべて小文字で区切りはアンダースコア）で書くので区別できるでしょう。

cd  __Project__
code  __FilePath__

詳しくは、チュートリアルや手順書を手軽にするプレースホルダーの書式を参照してください。

ここで一旦中断

構造化ドキュメンテーションの特長はまだまだ説明しきれていませんが長くなってきたのでここで一旦中断します。構造化ドキュメンテーションを応用するとテキスト形式のファイルに対して次の様式を書くことができます。

チケット（今していること、スタック）
手順書
暗記カード
コールツリー
データ構造
デバッグメモ
トラブルシューティング
役所等での手続き、一般教養、生活情報などの整理またはヒント
メディアライブラリの整理、診察券や電池などの収納場所
他

もちろんこれらの様式全てに対して全文検索することもできますし、様式の中に typrm のタグでリンク関係を書くこともできます。

これらの様式の書き方にはそれぞれコツがあるのでまた別の機会に説明したいと思います。次の構造化ドキュメンテーションの記事をお楽しみに！

Note as Code： 簡単に編集ができるアジャイルなノートを書こう

見出し： 見出しのツリーを作り、折り畳んでから選ぶ

特長： YAML 形式と typrm タグ を使うメリット

サンプル

環境： 構造化ドキュメンテーションを書く環境を整える

基本： 初めての構造化ドキュメンテーション

項目名： 項目名を書くと読まなくても単語で探せるようになる

複数行の値： YAML の文法を無視するブロックには バーティカル ライン (|)

早く探す： 早く選べるように見出しを短くして概要を書く

フォーカス： 注目すべき場所を強調表示する

コピペ： コマンドをキーボードで入力するのは時代遅れ