構造化ドキュメンテーション

深刻な情報不足の解消へ

筆者は現役のプログラマーとして30年近くになりますが、その間にいくつも技術革新が起き、スキルのアップデートをしてきました。新しいプログラミング言語、フレームワーク、OS、セキュリティ、バックエンド、フロントエンド、クラウド、開発手法など多岐に渡ります。それらをキャッチアップする手段として構造化ドキュメンテーションによる手順書を書いてコピペしてきました。

取扱説明書やアプリケーションの使い方の書籍を見てみると、スクショが貼ってあり、見ただけで分かるようにし、小学生でも読めるように専門用語を使わずに簡単な文章で書いてあります。動画でも操作手順が説明されていることもあり、見た通りに操作すれば手順をこなせます。

にもかかわらず、書いてある通りに操作してもできないことがあまりに多くないでしょうか。そんなときの手順書の筆者の言い訳はこのようなものでしょう。

スクショや動画を見れば一目瞭然だから分からない方がおかしい
バージョンアップやユーザーの状況によって異なるからスクショと違って当然
前提となる状況になっていないから、そこは調べて欲しい
書いてあるけど、その状況でやってはいけないのは当たり前
そもそもこれは手順書ではない（手順書は存在しない）

このように、できない原因は、書いてある内容が難しすぎて理解できないことや読めないことではありません。できない原因は、書いてあることと実際に起きていることが違っていることや、必要な情報が書かれていないことです。つまり情報不足なのです。

本記事では、シンプルに書きつつ情報不足にならないことを目的とした 13のルールを説明しています。大量の情報を少ないコストで書くには、アジャイルな性質を持つ構造化ドキュメンテーションが適しています。この文書の最後まで読めば、なぜ構造化ドキュメンテーションと呼んでいるのかも分かります。

操作ステップを構造化する

スクショを使った一般的な手順書の場合

構造化ドキュメンテーションの話をする前に、一般の手順書がどういうものなのか踏まえておきましょう。一般の手順書には大量のスクショが貼ってあり、どこを操作するのかが図示されています。

Excel を開き、Home のリボンを選びます。

Clipboard（📋）ボタンを押します。

Paste メニュー項目を選びます。

このように大量のスクショがある手順書は確かに見やすいのですが、スクショを撮って図形を付けるといった数分かかる作業がかかってしまいます。会社の多くの人が参照する手順を共有するのなら良いですが、個人やチームで数百もの専門的な手順にスクショを作っていくことはとても非効率です。

文字だけよりスクショがあるほうが読む人の気が滅入らないというメリットはあると思います。その目的のためであれば手順書にスクショ 1枚だけで十分でしょう。しかし、自分のための手順書にスクショを撮ることは稀だと思います。

ちなみに、スクショの数を少なくしたいのなら、操作する場所に順番を表す数字を添える方法もあります。しかし、そのスクショを読むときは数字を探さなければならないという欠点があります。スクショが全く無いよりかは有った方が良いですが、画面を移動するとコンパクトにできないので、やはりコストが高いです。

ところで、何か困った時にサポートに電話して聞くことがあると思います。そのときスクショを見せられて解決したわけではないですよね。サポートが言うのは次のような情報です。

画面のタイトル名（マッチング）
ボタンなどの名前（マッチング）
ボタンなどの位置、上下左右、色（マッチング）
検索キーワードやコマンドのアルファベット（詳細情報）
操作したことを確認してから、次の操作を示す（順次、反復）
状況に応じた説明（条件分岐）

実際、スクショが無くてもこれらの情報があれば十分に手順をこなすことができます。「（画面のタイトル名）を開いて（位置）にある（ボタン名）を押してください。」といった文章を書く必要もありません。そのことに薄々気づいている方は多くいると思います。

以下では、スクショを使わずにかつ情報不足を起こさずに構造化ドキュメンテーションだけでアジャイルに手順を書いていく方法について詳しく説明していきます。

サンプル

たとえば、iPhone（iOS17）でモバイル通信をオフにするための操作手順を一般的な丁寧な文章で書いてみます。

iPhone のホーム画面を開いて「設定」アプリを開き、設定メニューの中から「モバイル通信」を選び「モバイルデータ通信」をオフにします。

一方、構造化ドキュメンテーションでは操作手順の区切りを表す >> を使って書きます。

iPhone >> ホーム >> 設定（アプリ）>> モバイル通信（中央）>> モバイルデータ通信（上）=オフ

パッと見た印象でも、操作ステップが明確になって読みやすくなりましたね。文章で伝えることがいかに効率が悪いかが分かります。PC やスマホなどの IT 機器をまったく触ったことがない人には文章で書かれていないと分からないのではないか、文章で丁寧に説明しないのは失礼ではないか、と考える方はもう一度よく考えてください。文章を読むことだけが分かる方法ではありませんし、丁寧すぎるのに的を得ていない文章を読まされると怒りがわいてくるものでしょう。

操作しているときの様子を思い出してください。

えーと「設定」アプリはどこだ〜。ここだ（タップ）。設定アプリが開いたぞ。次に「モバイル通信」はどこだ〜。ここだ（タップ）。画面が変わったぞ……

このように操作対象だけ意識し、それ以外の言葉、たとえば「開く」「選ぶ」の違いは意識していないので「開く」「選ぶ」などの単語は必要ありません。逆に「開く」「選ぶ」で操作方法が違うのではと考えてしまいます。

構造化ドキュメンテーションによる手順書の雰囲気が掴めたところで、以下で具体的に書き方を説明していきます。自分のメモにこのような手順を書いたことがある人は多くいると思いますが、情報不足にならないためにはいくつかのルールを意識して書く必要があります。それを詳しく説明していきます。

ルール1. 操作ステップごとに >> で分ける

構造化ドキュメンテーションでは >> を書いてステップごとに分けます。それくらいなら分かるよと思われる方が多いと思いますが重要なルールがあります。それは、

ユーザーの操作ステップごとに分けること
ユーザーの操作ステップを書くこと

です。同じことしか言ってないように聞こえますが違います。たとえば、

>> ホーム >> 設定 >>

を

>> ホームにある設定 >>

にまとめてはいけませんし、

>>（リンクを右クリック）>> 新しいタブで開く >>

を

>>（リンクの コンテキスト メニューの）新しいタブで開く >>

のようにまとめてはいけません。厳密に操作ステップごとに分けることです。

逆に、ユーザーの操作ステップに含まれないことを >> で分けてはいけません。たとえば、タップしないグループ名を

>> 2つ目のグループ >> モバイル通信（中央）>>

のように分けるのは良くありません。グループから徐々に狭めていくとは限らないからです。操作ステップごとに書かれていることを期待するユーザーは、タップしたら何か反応があることを期待してしまい、反応が無いと思った通りに動かないじゃないかと判断されてしまいます。この場合、

>>（2つ目のグループの）モバイル通信（中央）>>

のように >> で分けずにカッコ内に書きます。

スクロールは画面が大きいとスクロールの操作が不要になるかも知れないので分けません。しかし、多くの場合でスクロールが必要なら分けてもいいでしょう。そこに正解はありません。

>>（下へスクロールして）アクセシビリティ >>

>>（下へスクロール）>> アクセシビリティ >>

このルールに従って書くようになると気づくと思いますが、手順書には操作の意味や目的ではなくユーザーの操作ステップ（操作内容）について書きます。コピーの操作方法は、

キーボードで Ctrl + C キーを押す方法

だけでなく

マウスで右クリックしてコピーを選ぶ方法

もあります。どちらの操作をするかは人によるので、「コピーする」と書くのが良いと考えるでしょう。しかし、それは曖昧な表現による情報不足を自ら起こしたことになります。網羅していなくても具体的に操作内容を書いてください。どちらか片方の操作方法だけで構いません。網羅的であることを満たすために文章が抽象的になったり長くなったりすることよりも、書いてある通りに操作すればできることのほうが重要です。今までどれだけ曖昧な表現や状況判断が必要な表現で苦労してきたか思い出してください。

ルール2. 上下左右中央を（）の中へ

それぞれの操作ステップには、（）の中に 上下左右中央 を添えて書きます。

>> モバイルデータ通信 >>

>> サウンドと触覚 >>

ではなく、以下のように書きます。

>> モバイルデータ通信（上）>>

>> サウンドと触覚（やや下）>>

この情報によって探す範囲が9分の1に狭まります（野球のストラックアウトの 3×3=9 のイメージ）。この効果は意外とかなり大きいです。場所を指し示されるとしっかりと探す意識が強くなるのも1つの要因です。目立つ部品を示してその上下左右と書くのも有効です。スクショよりざっくりしていますが十分に見つけられます。

操作対象の色も有効性が高い情報です。これは説明するまでもないですね。

>> バッジ（アイコンの右上の赤い数字）>>

ちなみに、開いた画面のスクショがあると今までの操作が間違えていなかったと安心できますが、次の操作が見つかることでも十分に安心材料になります。

ルール3. 画面に書いてあることを書く

手順書には、画面に書いてある文字（キーワード）を一語一句たがわずにそのまま書くことです。なぜなら、ユーザーはその言葉を探してしまうからです。また大きなメリットがあります。それは、ブラウザーのページ内の検索機能を使ってキーワードをコピペすることで、ユーザーの操作が早くかつ簡単確実になることです。

たとえば、画面に「email」と書いてあるときに、手順書に「電子メール｣や「e-mail」と書いてはいけません。たとえ、画面に書いてある表現が間違っていたとしてもです。

画面に書いてある言葉以外は基本的に（）の中に書きます。email だけでは分からない人を対象に説明するのなら「email（電子メール）」と書きます。画面に書いてある表現が間違っていたら、カッコ内に正しい表現で書きます。

ボタンについては、よくボタンの画像だけでボタン名が表示されていないことがありますが、その場合は操作内容ではなくボタンなどの見た目をまず（）の中に書きます。

>>（歯車ボタン）>>

マウスを合わせればボタン名が表示されますが、その場合はカッコの外にボタン名を書きます。

>> 設定（歯車ボタン）>>

ほとんどの操作対象にカッコが付く場合は、逆に画面に書いてあるものを「」で囲みます。

>>（バックアップするファイルを選択）>> ごみ箱（へドラッグ＆ドロップ）

ではなく、以下のように書きます。

>> バックアップするファイルを選択 >>「ごみ箱」へドラッグ＆ドロップ

理由は、カッコがある部分に比べて、カッコが無い部分は見つけにくいからです。

ルール4. 絵文字を使う

ボタンの画像は、絵文字や記号に似たものがある可能性があります。たとえば、プログラムの実行を開始するときは、再生の絵文字 ▶ と似ていることがほとんどでしょう。

…▶≡↺🔄✂️💾📋

ネットで検索すればもっと見つかると思います。

また、Office アプリケーションなどのよく使われるボタンについては、ボタンの画像だけでなくボタン名も表示されています。手順書を書くときは、よく使われないボタンに関してもボタン名を書きます。マウスを合わせて表示されるボタン名です。

>> 実行 ▶（左上）>>

ルール5. タップ以外の操作は（）の中へ

タップ（クリック）以外の操作に関しては操作内容を（）の中に書きます。これは画面に書いてある言葉以外は基本的に（）の中に書くルールと同じです。

>> Windows スタート（を右クリック）>> デバイス マネージャー

>> 電源 ボタン（を長押し）>>

>> Windows スタート >> デバイス（と入力）

トグルにチェックを入れるときはタップするかしないかどちらかなので、どういう状態にするかを（）の中に書きます。

>> 自動的に再起動（にチェック）

タップすることがどういう意味か分からないとき、たとえばテーブルのタイトルをタップしてソートするときは、意味が分かるように（）で説明します。

>>（ファイル一覧を）サイズ（でソート）

ルール6. ボタン、タブ、メニュー、キーなどを明示する

ボタン、タブ、メニュー、ツリー、ビューなど一般に知られている GUI 部品の種類については（）の中に入れないほうが読みやすいです。「ボタン」などの言葉自体は画面に表示されていませんが書いてあるほうが探しやすいです。なお、GUI 部品の種類の前に空白文字を入れると理解がしやすいです。

>> OK ボタン >>

>> 詳細 タブ >>

GUI 部品の種類の名前に何を使うかには注意してください。たとえば、アップルのサイト https://developer.apple.com/jp/support/renewal/ には

アカウントの「メンバーシップの詳細」セクション

と書いてありますが、セクションは色々な意味で使われる曖昧な言葉なのて何を指しているのか分かりません。

アカウント >> メンバーシップの詳細 タブ

のように「タブ」という GUI 部品の種類の名前を書くと目線が上に行き、すぐに見つかります。

ちなみに「アカウント」の部分はハイパーリンクになっているので、手順書では URL に置き換えます。

https://developer.apple.com/account >> メンバーシップの詳細 タブ

メニュー（GUI 部品の種類）も「メニュー」と明示的に書きますが、メニューを展開したときのサブメニューやメニュー項目については「メニュー」を省略します。

>> ファイル メニュー >> 名前を付けて保存 メニュー

ではなく、以下のように書きます。

>> ファイル メニュー >> 名前を付けて保存

メニューという言葉には目線が上に行くという効果があり、それを避けるためです。

キーボードのキーを押すときは「キー」を書きます。

>> F5 キー >>

項目の入力やテキストの編集を構造化する

ルール7. フォームへ入力する手順書はフォームで書く

フォームにある複数の項目に入力する手順を書くときは、手順書もフォームのように書きます。ただし、全ての項目を書く必要はありません。

スケジュールを追加します:
    メニュー: iPhone（iOS17）>> カレンダー >> ＋（右上）
    タイトル: ____
    終日: オフ  #// オンまたはオフ
    開始: __StartDateTime__  #// 補足情報を表すプレースホルダー
    移動時間: 5分  #// 例。通常指定する値が固定の場合
    追加 ボタン（右上）:

多くの場合、フォームや画面を表示するまでの操作ステップがありますが、それは メニュー: のフィールドに書きます。実際のフォームには メニュー: という項目はありませんが、YAML で書くときは メニュー: の部分を削除すると書式エラーになってしまうからです。エラーになる原因は、値を持つフィールドに子フィールドを持たせることが YAML ではできないからです。

スケジュールを追加します:                    ... フィールド名
    iPhone（iOS17）>> カレンダー >> ＋（右上）   ... 値
    タイトル: ____                            ... エラー

フォームや画面を表示するまでの操作ステップは、メニューの GUI 部品から選ぶことが多いので、メニュー: というフィールド名を書きます。構造化ドキュメンテーションによる手順書では、メニュー以外の GUI 部品を操作してフォームを表示する場合でも メニュー: というフィールド名に統一します。GUI 部品のメニューとフィールド名に書かれるメニューは別の概念です。後者はフォームを表示するまでの操作ステップを表す概念です。以前は適切なフィールド名を適宜付けていましたが、統一されていないとフォームの項目名を指していると勘違いすることや、実際のフォームの項目名に衝突することがあったので却下になりました。

ルール8. プレースホルダーはアンダースコア2つで囲む

前章のサンプルにある __StartDateTime__ や ____ はプレースホルダーです。両端のアンダースコア _ 2文字は下線のイメージです。文字がある部分（StartDateTime）の下には下線がありませんが下線があるものと想像すれば、紙のテストの穴埋め問題に見られる表現と同じであると気づくでしょう。また、アンダースコアの間は大文字から始める Pascal ケース（スタイル）の英語、または日本語（ドキュメントの言語）で書きます。日本語のドキュメントでは英語でプレースホルダーを書く方が見やすいです。

プレースホルダーは見た目でそれ以外と違いがあると分かるように表現することが大事です。多くの手順書にはサンプルの値または設定すべき値が入っていて、プレースホルダーであるかそうでないかの見分けがつきません。構造化ドキュメンテーションによる手順書では __ で囲まれた部分はプレースホルダーであるというルールがあるので、客観的に見分けられます。もし、そのルールがないと、書かれている値をそのまま入力すべきか、それとも状況に応じて置き換えて入力すべきかをユーザーが解析することになってしまいます。ちなみに、Python には __init__ などのメソッド名がありますが小文字から始まるキャメルケース（スタイル）なのでこれも区別できます。

プレースホルダーを ${StartDateTime} のようにシェルの変数と同じ書式で表現された手順書がたまにありますが、変数は変数であると認識されてしまうのでこれも良くないです。たとえば、Visual Studio Code の launch.json ファイルの PATH フィールドなどの説明（下記）を読むと、${workspaceFolder} の部分を置き換えるべきと読めてしまいますが、実際の launch.json には置き換えずにそのまま入力します。

launch.json の一部:

PATH: ${workspaceFolder}/bin

ルール9. 編集は編集前と編集後を示す

たとえば、YouTube の動画の途中から再生する URL を作る方法を文章で説明するとこうなります。

URL をコピーして URL の末尾に「?t=秒数」を追加します。

この説明を聞いて試してみようと、YouTube の動画ページを開いて URL の末尾に ?t=300 を追加させたとします。しかし、いまいち確信が持てない感じがするでしょう。実際、URL の末尾に追加しても期待通りに再生されません。

こういったテキストの編集に関しては、編集前と編集後の書式やサンプルを示します。フォーラムでバグ報告や改善提案をするときのテンプレートによくある「期待する結果」と「実際の結果」に近いです。

書式:  #focus: t=
    編集前: https://youtu.be/__MovieID__?__AdInfo__
    編集後: https://youtu.be/__MovieID__?t=__Second__
サンプル:  #focus: t=
    編集前: https://youtu.be/yKDGsXzQ7gY?si=OX-mWBJBwUETbbPi
    編集後: https://youtu.be/yKDGsXzQ7gY?t=300

このように書くと気づいたかもしれませんが ?t=秒数 追加しただけではないですね。si=なんちゃら の部分が削除されています。これが期待通りに再生されなかった原因です。

なぜ文章で書くと分かりにくいかというと読む文章と操作対象の間がメタな関係だるからです。一方、編集前と編集後と操作対象にはメタな関係はなく、編集時に画面を見るときと一致するので分かりやすいのです。

また、Visual Studio Code など通常はプログラミングに使うテキストエディターには選択した部分と同じ内容の別の場所も強調表示される機能があります。この機能を応用すると、注目させたい部分を強調表示させることができます。

#focus: は注目すべきワードを示すための typrm のタグです。テキストエディターで #focus: の値に書かれた t= をマウスで選択すると、編集後の t= も強調表示されるので、編集する場所がすぐに見つかります。

また、差分がある部分も簡単に探すことができます。編集前の URL の先頭からマウスのドラッグを開始して、右方向へマウスのドラッグをしていくと、編集後の URL のうち同じ内容の部分も同様に強調表示されます。

そのまま右へドラッグし続けると t= の部分で編集後の強調表示が無くなります。なぜならそこで内容が変わるからです。強調表示が無くなった部分に注目して編集しましょう。

手順を見つけやすく構造化する

ルール10. することと手順を分ける

構造化ドキュメンテーションによる手順書では、何をするための操作なのか（すること）を YAML のフィールド名にして、そのフィールドの値に操作内容を書きます。

モバイル通信をオフにします:
    iPhone >> ホーム >> 設定（アプリ）>> ...

多くの手順書は、することと操作内容が同じ章や文節内にまとめて書かれてしまっています。

モバイル通信をオフにするには iPhone のホーム画面で設定を開いて ...

これでは、探している内容が見つかったと判断することや、ここには書いてないから次の候補となる場所を探すこと（総じてマッチング）は文章をすべて読まなければできません。することと手順を明確に違うスタイルで書くことでマッチングのために読む量がかなり減ります。なぜなら、明確に違うと読み飛ばすことが簡単になるからです。

モバイル通信をオフにします:
    iPhone >> ホーム >> 設定（アプリ）>> ...
スケジュールを追加します:
    iPhone >> ホーム >> カレンダー（アプリ）>> ...

別の記事に詳しく書きましたが、フィールド名は短くして、詳細はコメント（# または #// の右）に書くとさらにマッチングが早くなります。

モバイル通信をオフ:  #// 4Gなどのキャリアによる通信を使わないようにします
    iPhone >> ホーム >> 設定（アプリ）>> ...

ちなみにググってよく見つかる手順書のブログでは、することの文章が長すぎて読むのに時間がかかります。マッチングを間違えないようにすることが大義名分のようですが、実際はライターの文字数単価が低いためにだらだらと長く書いていることが原因でしょう。それを良しとするグーグルもどうかと思いますが、現在では AI に聞いた方が早いですし、それよりももっと早いのはこの構造化ドキュメンテーションです。

することの文章は断定表現で書きます。受動態ではなく能動態で書きます。これはよく言わますね。また「できます」と書かれることが多いですが、これはユーザーを不安にさせてしまうので自信がなくても「します」と書きます。また「〜であるかどうかを確認する」ではなく「〜であることを確認する」と書きます。また「する」より「します」のほうが印象が良くなります。

余談ですが、プログラムのソースコードでも、することを先に読めるように、コメントを上に書きます。下記のサンプルはシェルスクリプトのコードです。

#// CPU の使用率のトップ3を表示します
top -bn 1 | grep CPU -A 3

コードの補足説明をするとき（コードが主、コメントが従）は、コメントを右またはインデントを深くした下に書きますが、構造化ドキュメンテーションのコメントでも同様です。

sudo shutdown -h now  #// Linux をシャットダウンします

または

sudo shutdown -h now
    #// Linux をシャットダウンします

構造化ドキュメンテーションでの補足説明

モバイル通信をオフ:  #// 4Gなどのキャリアによる通信を使わないようにします

または

モバイル通信をオフ:
    #// 4Gなどのキャリアによる通信を使わないようにします

ルール11. することとケースを分ける

何かが起きたとき（ケース）から始まる手順書の場合、ケースと手順を分けて両方とも書きます。片方だけ書いてヨシとしないでください。それこそが情報不足の1つの要因です。なぜなら、何かが起きたときにユーザーがすることを分かっていたらすることを探し、分かっていなかったらケースを探すからです。

バッテリー不足の警告がされたとき:
    iPhone >> ホーム >> 設定（アプリ）>> ...

や

モバイル通信をオフにします:
    iPhone >> ホーム >> 設定（アプリ）>> ...

ではなく、以下のように書きます。

バッテリー不足の警告がされたとき:
    モバイル通信をオフにします:
        iPhone >> ホーム >> 設定（アプリ）>> ...

全体の文章量が多くなったときは、ケースごとに分けたツリーと機能ごとに分けたツリーが作られるようになります。その場合、リンクを書き、どちらのツリーからでもたどれるようにします。

機能:                                 #// 機能ごとに分けたツリー
    モバイル通信をオフにします: #keyword:            #// リンク先
        iPhone >> ホーム >> 設定（アプリ）>> ...
    ____します:
        ...
    ____します:
        ...
    ...
困ったときは:                         #// ケースごとに分けたツリー
    バッテリー不足の警告がされたとき:
        モバイル通信をオフにします: #search:         #// リンク元
    ____のとき:
        ...
    ____のとき:
        ...

※ #keyword: と #search: はリンク関係を表す typrm のタグです。

ルール12. 前提条件を明示する、リセット状態から始める

ある操作をする前に必要な操作があること（前提条件を満たすこと）はよくあります。たとえば、フォームの項目に入力する前にログインすることなどです。前提条件を書かなければならないことは、多くの人が分かっていると思いますが、めんどくさいので書かないことがあります。しかし、それではマズイと文書のテンプレートを作る人が考えて、前提条件の章をテンプレートに入れることもあるようです。それだけ前提条件を満たすことは手順をこなす上で重要なことなのです。

なるべく少ないコストで前提条件を書くには、前提条件を満たすためによく行う手順を章に分けて書き、前提条件を満たす手順の章へのリンクをそれぞれの手順の前に書くことです。

第一章:
    前提条件:
        〜をしてなかったら〜をします。詳細はこちら。
    手順:
        ...
第二章:
    手順:
        ...

ではなく、以下のように書きます。

第一章:
    前提条件:
        〜をしてなかったら〜をします。詳細はこちら。
    手順:
        ...
第二章:
    前提条件:
        #search: 第一章 >> 前提条件
    手順:
        ...

前提条件を常に書くように心がけていても、前提条件の存在自体を見逃す可能性があります。特にプログラムのインストールに関する手順では、見逃す可能性をなくすためにOSのリセット状態から始めなければ情報不足の 1つの要因になってしまいます。必要なプログラムがすでにインストールされている状態から動作確認をして作った手順書は、そのインストールが不足しているために、ユーザーは手順通りにやってもできない可能性が高いです。なので、OS のバックアップをするプログラムや仮想化プログラムを使い、いつでも初期状態の OS から始められるようにしておきます。こういったことをさっとやってしまうのが優秀なエンジニアです。

ルール13. 構造化プログラミングのように順次や分岐を書く

手順書の内容を書く順番はユーザーが操作する順番に合わせます。あたりまえのことですがこれができていない手順書が多くあります。たとえば、Apple Developer Program の更新ページの「Apple Developer Webサイト」を見てみましょう。記事を書いた当時の文章の構造は次のようになっています。

Apple Developer Program の更新:
    年間メンバーシップの更新:
        Apple Developer Webサイト:
            - 〜すれば自動更新できます。
            - 別の方法では、期限切れ30日前から手動更新でき、更新方法は〜
            - 有効期限後に更新する場合は〜
        Apple Developerアプリ:
    （以下略）

Apple Developer Webサイトと Apple Developerアプリの両方が必要なのでしょうか。

よく読むとどうやら前提条件やシステムによって章が分けられているようで、何らかのポリシーがあるようです。しかし、この手続きを完了するまでには、章が分けられているにも関わらず、3回ぐらい全部を読み返してしまいました。なぜそうなってしまったのでしょう。

原因は、ユーザーの手続きするときの順番に文書が合っていないからです。

ユーザーが手続きするときは、まず自分がどの前提条件に該当するかを調べます。このページを読むために調べることは以下のとおりです。

自動更新をサポートしている地域に自分がいるかどうか
現在が期限切れまで 30日より前か、30日以下か、有効期限後なのか（期限切れの日を）調べる
Web サイトを使うかアプリを使うか決める。ログインできることを確認する

これらを調べるには、契約内容を表示するなどの操作が必要になります。契約を思い出すか紙の契約書を見てください、で済む時代は過ぎました。つまり、このページの最初に書くことは、どの章を読むべきかを調べる手順です。そして調べた結果に応じて読むべき場所の分岐をユーザーにガイドします。こういった前提に気づけるのは動かないものは動かないブログラミングの経験があったからではないかと考えています。ミスってもよろしくやっといてと誤魔化せるSEでは気づかないでしょう。

Apple Developer Program の更新:
    自分の契約を調べる
        Apple Developer Webサイトを使う場合:
        Apple Developerアプリを使う場合:
    年間メンバーシップの更新:
        自動更新が設定されている場合:
        自動更新が設定されていない場合:
            期限切れまで 30日より前の場合:
                Apple Developer Webサイトを使います
            期限切れまで 30日以下の場合:
                Apple Developer Webサイトを使います
            期限切れの場合:
                更新手続きをします
    （以下略）

フローチャートの条件分岐にあたるタイトルは 〜の場合: のように書きます。

分岐をした後に共通の手順が続くときは、分岐の最後に #// 以下に続きます と書きます。これを書かないと、ユーザーが続きの手順をしないで終わってしまうことがよく発生します。

このような、順次、分岐、反復、呼び出しは、プログラミングにおいては構造化プログラミングと呼ばれています。手順を自動的に行うなら構造化プログラミング、手動で行う手順書を書く方法なら構造化プログラミングの知見を活かした構造化ドキュメンテーションというわけです。構造化ドキュメンテーションで YAML を採用した理由は、構造化プログラミングができる Python に似た構文を持っているからです。

ユーザーが手続きするときの順番はバージョンが上がるたびによく変化します。よく変化することに対応するには、俊敏さ（アジリティ）が必要です。だからアジャイルに編集ができるテキスト形式の構造化ドキュメンテーションが適しているのです。

（プログラミング編）

構造化ドキュメンテーションによる手順書は、プログラミングをサポートすることにも有効です。こういうことをしたいときは、どのようにコーディングしたらいいかについて構造的に理解することができます。長くなってしまったので、別の機会に説明します。

深刻な情報不足の解消へ

操作ステップを構造化する

スクショを使った一般的な手順書の場合

サンプル

ルール1. 操作ステップごとに >> で分ける

ルール2. 上下左右中央を（）の中へ

ルール3. 画面に書いてあることを書く

ルール4. 絵文字を使う

ルール5. タップ以外の操作は（）の中へ

ルール6. ボタン、タブ、メニュー、キー などを明示する

項目の入力やテキストの編集を構造化する

ルール7. フォームへ入力する手順書はフォームで書く

ルール8. プレースホルダーはアンダースコア2つで囲む

ルール9. 編集は編集前と編集後を示す

手順を見つけやすく構造化する

ルール10. することと手順を分ける

ルール11. することとケースを分ける

ルール12. 前提条件を明示する、リセット状態から始める

ルール13. 構造化プログラミングのように順次や分岐を書く

（プログラミング編）

ルール6. ボタン、タブ、メニュー、キーなどを明示する