📖

ドキュメントデッキ ～カードとデッキを用いた楽しくて読みやすい執筆手法～

に公開
Markdown
document
documentation
idea

まとめ

  • ドキュメントデッキという筆者考案の執筆手法を紹介した
  • 概念:
    • カード（1話題1ファイル）
    • デッキ（カードのリンク集）
  • つくりかた:
    • GitHub + Markdown
    • ファイル名は機械的に連番、タイトルはファイル一行目、スクリプトでカードリストを自動生成
    • 正式なデッキはおそらく index.md になるだろうが、もちろん他にもつくっても良い

はじめに

ドキュメントデッキという執筆手法を考案しました。

といっても大したものではなく、ビルディングブロック的にページをつくった後、そのリンク集をつくってコンテンツの入口にしようというものです。

ありきたりな発想でしょうし、すでに誰かが似た手法を提案してそうです。ドキュメントデッキは以下の点で新規性があると思います。

  • カードとデッキでたとえたこと
  • ファイル名を連番にする、との意思決定を採用したことでカードやデッキのたとえにふさわしい使い心地（作り心地）を実現できていること
  • 本格的なサンプルがあること

サンプル

ASDM:

⭕❌

良い点⭕

  • つくりやすい
    • GitHub + Markdownなので書きやすいし、生成AIも使いやすい
    • カードづくりとリンク集づくりで分担しやすいので、協業でもつくりやすい（はず）
    • 書籍レベルの構造化が要らず、カードつくって並べるだけなのでつくりやすい
  • 楽しい
    • VSCode で Markdown で、カードという小さな単位で少しずつ仕上げていく過程は楽しい
    • カードをどの順番で並べようか、どういうカテゴリーでくくろうかといった「デッキをつくる楽しさ」もある（と思う）

良くない点❌

  • 読みやすいかどうかが不明
    • 🐰どうだろう？
      • サンプルとして挙げた ASDM を読んでみてください！
      • 皆さんもぜひお試しください！「ドキュメントデッキ書いたよ！」とかあったらぜひ教えてください！
  • 慣れるまではかえって書きづらい・読みづらい
    • プログラミングというかビルディングブロック的な発想が強い
    • また書籍のような構造をしないということは一貫性やストーリーが乏しいということでもあり、それらがもたらす強烈な魅力が生まれにくい
      • 🐰カードとデッキのつくりかた・見せ方次第な気もしますが。。。

つくりかた

4ステップあります。あくまで参考です。やり方に正解はないですし、自由でいいです。

Step1: カードの洗い出し

カードのネタを洗い出します。

  • ブレスト時に使うような発散的なツールで、カードのネタを洗い出す
  • 発散的に散らしたり、収束的に整理したりする
  • 🐰私はテキストエディタやノートアプリで箇条書きで書くのが好きですが、Miroのようなボードでもいいし、一気に喋って録音したものを生成AIで要約してまた喋って……みたいな繰り返しでもいいです。何でもいいのです（後述 Q&A も参照）
  • 最終的には目次レベルを目指したいが、章節項でいう章だけでいい
    • 🐰節や項などの単位をどうするか各カードに任せます

目次レベルで「大体こういう分類でこういうカードを配置すれば良さそう」が見えてきたら、次に進みましょう。

Step2: カードの作成

1-話題 1-ファイルで Markdown ファイルをつくっていきます。

  • ファイル名
    • 機械的に連番にする
  • ファイルの中身
    • 自由。フォーマットを決めてもいいし、決めなくてもいい
    • しかし 一行目はタイトルにする
      • あとでカードリストを自動生成するために必要

Step3: デッキの作成

デッキ（リンク集）をつくります。

  • 最低でもカードリストはつくる
    • カードリストとは、すべてのカードをリストアップしたファイルのこと
    • スクリプトで自動生成するべき
    • 例:
      • ASDM では 000.md をカードリストにしており、scripts_000.py で自動生成している
      • 🐰スクリプトは Cline でつくりました。この程度なら自分で書くより早いですし一発で期待どおり動作するブツが出てきます。便利な世の中になりましたね
  • 最終的にはトップページ（index.md）をつくることになると思う
  • デッキは別にいくらでもつくれるので、気軽につくって議論や検討の肥やしにするといい

Step4: ドキュメント全体の構成の決定・収束

ここまででカードとデッキを行き来してあれこれつくっていると思います。最終的なドキュメントに向けて、全体の構成を決めます。

  • 決めることの例:
    • 各カードのフォーマットは結局どうするのか。統一するならどんなフォーマットを使うのか
      • 🐰カード新規スクリプトをつくって、フォーマットもそこに埋め込むと便利です（フォーマットがn通りあるならn個つくる）。ASDM でも newpage.py をつくっています
    • トップページのファイル名や中身
    • その他必要ページの網羅や整備
      • 🐰ASDM では README から辿れるように整えました。CONTRIBUTING.md や ADR があります

Step5: リリース作業とリリース

リリースに必要な準備と作業を行ってください。

Q&A

Q: カードの洗い出しってどうやるの？

Ans: 私が知的生産や発想法と呼ぶジャンルが必要になります。解説します。

ブレストはご存知でしょうか。正式にはちゃんとした手法であり、進め方があるのですが、カジュアルには「アイデア出し」くらいの意味で使われています。

このような営みは発想法と呼ばれることがあります。私は知的生産と呼んでいます。

やってることはそんなに難しくありません。アイデアを散らかして、それを眺めながらさらにひねり出して――と 発散 をしつつ、同時に、発散したものを眺めながら自分なりにグループ分けしたり関連してそうなのを固めたりなど整理していきます（収束）。発散と収束を繰り返すことで、そのうち「それだ！」という本質や全体構造が見えてくるので、ちゃんと表現します。最終的な成果物は「全体構造を表現した図」か、「本質を言語化した文章」のどちらか、あるいは両方です。

※基本的にひとりでやるべきです。複数人で一緒に行ってできるとは思えません。あるいは、複数人でやるにしても、「ひとりで行っている光景」を複数人分並べることで、他の人の様子も自由に見れる・内容を拝借できるようにする程度です。

使うツールは何でも構いません。極端な話、頭の中だけでもいいですが、天才でもないと難しいと思うので、普通は書きます。Miro のような付箋ツールがわかりやすいですが、Cosense のような箇条書きベースのツールでもいいですし、もちろんローカルでテキストエディタで書いてもいいですし、Workflowy のようなアウトライナーでも良い。私は使わないですが、音声入力もいけるかもしれませんね。

注意したいのは、グラレコ（グラフィックレコーディング）のように ビジュアルに頼った「描く」ではなく、言語化して言語で書く ということですね。ビジュアルに逃げてはいけません。ちゃんと頭を絞って、ひねって、言語化してください。ただし、一概にも言えなくて、モチベーションを維持したりインスピレーションを湧かせたりするのに描くことが役立つこともあります。

Q: カードはどうやってつくっていくの？

Ans: 正解はないですが、雑でもいいので書いてみるといいと思います。

書いていくうちに「こう書けば良さそう」とか「こういうフォーマットで統一できそうじゃないか」などが見えてきます。

一つの目安として 10+1 はいかがでしょうか。、10枚ほど雑なカードをつくってみましょう。また1枚だけガチクオリティのちゃんとしたカードをつくってみましょう。これくらい使ってみたら、だいぶいろいろと見えてくるはずです。もちろん「ドキュメントデッキはやめとこう」に至る可能性もあります。ドキュメントデッキは万能ではないので、それはそれで良いことです。

GitHubで編集を提案

Discussion