記事のテンプレート
要約
- これは技術記事でない。
- テンプレートを用意した。
- テンプレートの紹介もする。
目次
始めに
はてなブログに投稿する用に、簡単なテンプレートをいくらか拵えた。項目のうち幾ばくかが各記事で統一できるのに気づいたのもあるが、一番の目的は、記事を書くときになるべく考えることを削りたかった、というものだ。ちなみに筆者のやり始めた記事の書き方は、まずざっくりと大見出しだけ並べて構成を考え、その後小見出しでそれぞれを補足していき、最後に中身の文章を書く形だ。こうすると無駄に冗長な文章になったりせずに済むし、見出しになぞらえて論を展開することによって論点がずれるのを防ぐことができる。
ところで以下に掲載するテンプレートにもあるが、表示される際にマークダウンがHTMLに変換されることを利用してHTMLのコメントをマークダウンに書き込む、という荒業が存在する。この手法は現在携わっているプロジェクトを進めているときに知った。IssueとPull Requestのテンプレートを制作しているときに、もう組まれていて使えるようになっているテンプレートが公開されていたので、それを採用していくつか項目を削った形なのだが、その公開されていたテンプレートこそに荒業が使われていたのだ。実際、下手にマニュアルを用意するより、テンプレートに直接コメントを書き込んだほうが遥かに生産的であるように思う。
テンプレート
さて、テンプレートについて、以下の見出しでまたある程度詳細に記述する。
意図
まずもって言えることは、筆者が潔癖症1であることだ。故に、こういった記事も元々フォーマットを統一したい性質なのである。TypeScriptを初めて触ったときもとりあえずルールをそれなりに縛ったし、eslintにしても無効化しているのはフォーマットにあまり関係ない、煩わしい部分のうち数個程度だったりする。そういう訳で、こういったテンプレートを作成したのに本来深い意味合いはなく、単に気持ち悪くなったからやっただけでしかないのだ。
ところで、テンプレートを作るに当たって、まず基本となるbase、それらを拡張したproject、techとオブジェクト指向的にテンプレートを用意したのだが、マークダウンの記事のテンプレートはクラスのように継承することができず、作成するときにどうしてもコピーアンドペーストが発生する。こういったところも筆者には気になるところである。ケントバック2も重複は悪だと言っていた。偉い人が発する言葉に間違いはないのである。正解もないかもしれないが。
効果
単純にまず挙げられるのは、統一されたフォーマットで書かれることによって、記事の可読性が増す。日本語なのに可読性というとおかしいかもしれないが、たとえば絶対に冒頭に要約を載せると決めてあるので、筆者の記事の全ては要約だけ読めば内容は理解できるようになっている。他にも、(ないとは思うが)筆者の近況報告だけ見たいなら最後の終わりにだけを見ればいい。こういった風にフォーマットを整えることで欲しい情報を即座に参照できるようになり、有用性と理解へ至るまでの容易さが高まるのである。
しかしながら、筆者が最も狙っている効果であり、フォーマットの最たる長所であると考えている機能は実のところそれではない。筆者の考えるフォーマット最大の利点は、脳を殺して記事が書けることである。フォーマットに従ってルーチンワークでぼうっとしながらキーボードを叩いてさえいれば、勝手に記事が出来上がっているのだ。これほどうれしいことがあるだろうか。フォーマットを整えることで、指の肉体労働を極力減らし、かつ頭脳労働の分野にまで省エネを図ってくれる。素晴らしすぎて涙が出てくるぐらいである。ああ、素晴らしきかな、単純労働。極論を言うなら、時給五千円の針金を曲げるだけの仕事に就きたいものである3。
動機
ここも筆者なりのこだわりというのが表出してくる部分である。というのも、筆者はこういったテンプレートの統一や、エディタの設定、あるいは単純作業の自動化などは、なるべく最速で行うようにしている。もちろん優先度が低いものは後回しにするが、クリティカルな部分だと判断すれば、即座にその解決に向かう。
突然だが、筆者はクッキクリッカー4のようなゲームがそれなりに好きだ。特段効率の視覚化を好み、自分の書いたプログラムのログが出ている様子を延々眺めて楽しむようなタイプである。つまるところ、効率の最大化が筆者にとってのこの世にある中で最たる快楽の一つなのである。そこで話を戻すと、自動化などが特にそうだが、こういった終わったときからずっと効率があがるような仕様の確定は、長い目で見たときのそれに限れば、気付いた直後に執り行ったときに最大化すると言える。直近だけを見ればもちろん効率は落ちるので、どれほどの期間を見るのか吟味することも重要ではある。
テンプレート群
蛇足だが、以下に今あるテンプレート毎の解説をしていく。もし当ブログの記事の読み方を、先ほどの言葉で述べるところで、確定させておきたいのであらば、こちらが参考になるだろう。
base
以下の形が基本となる。
<!-- 全てのテンプレートの元となるテンプレート 構成規則 * この規則はCSSの見直しによって十分に変更されうる * 箇条書きは全てアスタリスク * 大見出しはh3 * 小見出しはh5 本文としての見出しの構成は、以下のようになる。 ### 本見出し * 箇条書きで要点説明 <br/> ##### 小見出しで上部に上げた一点を述べる --> ### 要約 * これは技術記事でない。 * テンプレートを用意した。 * テンプレートの紹介もする。 <!-- ここでまず全てを纏める。 先んじて要約を書いておくことで内容を確定させる要約駆動執筆もあり。 箇条書きだが特にハイパーリンクを強制はしない。 --> ### 目次 * [始めに](#始めに) * [終わりに](#終わりに) <!-- ここで目次をひたすら書く。項目がネストしている場合は目次もネストすること。 --> ### 始めに では以下からがこの記事の本文だ。 今回の記事は以上である。 ### 終わりに <!-- 感想でも近況報告でも。 -->
殆ど語るところはコメントに持っていかれてしまった。一応説明すると、他のテンプレートの元となってこそいるものの、コメントはそれぞれ適切に合うよう調整している。あくまで項目のみが原型なのである。
なお、基本的にはこの通りコメントに従って書いていけばいいのだが、別なルールも用意してあるので、そちらを参照した上での目lintも記事の執筆の上では必要不可欠だ。
project
projectは、今携わっているプロジェクトに関する記事を書くときに利用するテンプレートだ。そのために進捗、という以下の項目を追加してある。
### 進捗 現在の進捗は以下のようになる。 * [ ] メインページの作成 * [ ] サイドバー * [ ] Top * [ ] 投稿 * [ ] 検索 * [ ] 投稿表示 * [ ] 通知 * [ ] アカウントページ * [ ] ユーザページ * [ ] マイページ * [ ] 設定 * [ ] 認証系ページの作成 * [ ] ログインフォームの作成 * [ ] 新規登録フォームの作成 * [ ] リファクタ * [ ] 命名規則等の完全な統一
ネストして追加してあるタスクに関しては増減する。
ところでここまで進捗を公開していたらプロジェクトを直接教えているようなものだと、当記事を執筆している最中に気付いた。一応初回の記事でプロジェクトのチームメンバーの名前は伏せていたのだが、それも意味がなさそうである。別段完成したらこのブログでも宣伝するつもりであったし、特にこれといった問題もなさそうなので気にしないことにした。
tech
techはbaseからある程度コメントを調整したり最初に予防線の塊の記事へのリンクを張り付けたりしたテンプレートだ。こちらではなるべく個人の感想、感情、考え方、哲学は避けて、こういう操作をすればこういうものができあがる、ということにのみ記述する予定である。つまるところ、ノウハウの部類はtechのカテゴリのついているものの、実際には技術記事扱いではないということにするのである。
といったところで今回の記事は以上である。
終わりに
やはりテンプレートを作っておくと執筆が捗る。筆者は一時期物書きに憧れていた時期があったのだが、そのときも大筋のプロットから詰めていくタイプであったので、こういった項目の事前だった用意は歓迎するところである。
そして次の記事の話だが、もうそろそろ技術記事を用意したいと思っている。思ってはいるのだが、今思いついているネタは、中途半端にバグるgitのhookと、はてなブログのHTMLにおいてReactをビルドしたHTMLファイルのコピペは可能なのか、ぐらいしかない。後者はそれなりに突飛である自負があるのだが、地味に恐ろしいのが前者だ。詳細は省くが、こいつのせいで百個ほどコミットメッセージが吹っ飛んだ。おかげでこちらは大惨事だ。masterブランチにforced pushしたときは心臓が止まるかと思った。
閑話休題、次の記事はおそらく技術記事に行く前に一度プロジェクトの記事に入ると思う。現状やあったことをひとまずつらつらと書くだけなので何の面白みもないであろうことは宣言しておく。