読者です 読者をやめる 読者になる 読者になる

箇条書きより見出しを好め

Wikiesa なんかでひたすら箇条書きで記されているのを、最近たびたび見かけるようになった気がしたので話していた、文書構造のリファクタリングテクニックとなる。

基本は一番浅い箇条書きを大見出しにして、ネストを一段ずつ下げるといったものでざっくり以下のような図解で話していた。以下の例では大見出しになったものをタイトルとしており、中見出しが一番浅い箇条に対応している。初手としてはかなり手早く手を加えることのできるテクニックのひとつだと思う。

f:id:koic:20170310153214j:plain:w300

もちろん箇条書きが良くないといったものではなく箇条として成立していればよい。良くないのは箇条の重ね書きの結果として、箇条書きの4段ネストといったものなどで、それは既に箇条として破綻していたりする。そういった structure smell を作らないように積極的に見出しを導入しておくのがひとつの解だと思っている。

広く普及していると思われる Markdown 記法を例に、文書構造の変更前と変更後についてのイメージを次の Gist に書いておいた。

gist.github.com

文書構造の実例としては書籍が参考になるが、5年半くらい前にしたスライドなんかを引用したりして話していた。文書構造については一度身につけると長く使える能力になるので早めに身につけておくのがおすすめ。

www.slideshare.net


このあたりの話がいくつか書かれているアカシックレコードを夏くらいまでを目処に掘り起こしたい。