記事のテンプレート
要約
- これは技術記事でない。
- テンプレートを用意した。
- テンプレートの紹介もする。
目次
始めに
はてなブログに投稿する用に、簡単なテンプレートをいくらか拵えた。項目のうち幾ばくかが各記事で統一できるのに気づいたのもあるが、一番の目的は、記事を書くときになるべく考えることを削りたかった、というものだ。ちなみに筆者のやり始めた記事の書き方は、まずざっくりと大見出しだけ並べて構成を考え、その後小見出しでそれぞれを補足していき、最後に中身の文章を書く形だ。こうすると無駄に冗長な文章になったりせずに済むし、見出しになぞらえて論を展開することによって論点がずれるのを防ぐことができる。
ところで以下に掲載するテンプレートにもあるが、表示される際にマークダウンが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したときは心臓が止まるかと思った。
閑話休題、次の記事はおそらく技術記事に行く前に一度プロジェクトの記事に入ると思う。現状やあったことをひとまずつらつらと書くだけなので何の面白みもないであろうことは宣言しておく。
予防線の塊
要約
- これは技術記事でない
- 予防線の塊を記述した
- 技術記事の冒頭に載せるためのもの
- 予防線の塊は予告なく変更される場合がある
目次
始めに
この記事では、著者の記した技術記事に関する注意点を連ねていく。技術記事を参照するときはここに書いてあることを最低限理解してからが望ましいだろう。 では以下からがこの記事の本文だ。
予防線群
以下は当ブログの技術記事を読む上で、最低限読者に理解しておいて欲しい条項を纏めている。
本来当ブログとて、何の責も追わないただの一般的な個人が発信するインターネットの情報なのだから、情報の取捨選択及び信用の責任は全て読者にあると筆者は考えているのだが1、それを事前に再確認をとることで確たる承諾を得ることにしている。
なお、当記事は予告なく変更される場合あることに留意願いたい。
ではそれぞれの項目について述べる。
信頼性がない
まずもって言えることとして、筆者のブログの内容はソースを明らかにしていない場合2、第N次情報（N>1かつ自然数を満たす）であるということだ。これは十分に信頼に足るとは言えないものであり、またこれを活用する上では、その信頼性の欠如を考慮に入れた上で参考程度に留めておくのが当ブログの正しい利用方法と言える。
読者層の想定
そもそも論ではあるが、当ブログは極論個人の随筆を纏めた場であって、明示的に正しい情報のみを集積している訳ではない。またこちらでも述べていることとして、当ブログの記事は全てmarkdownで書かれたノートに過ぎない。一個人の、後で見返すために作成した資料以外の何物でもないのだ。間違っているかもしれないと注釈がついた、友人のノートを借りて読むような具合で記事を参照して頂けると有難い。
予防線は以上である。
終わりに
こういった記事は端的に無粋だし、またこのような記事に必要性があることなぞ遺憾という他ない。だがまあ、基本的にはあって損はないので、ひとまずはこういったように置いておく。 この記事は技術記事の冒頭に張り付けることにするので、度々修正を入れることになるだろう。 ところで、指摘や論理的な修正依頼、つっこみ等々は大歓迎である。予防線は誹謗中傷に属するものを避けるための護符であって、かつ責任問題を明確にすることで、もし何らかの人物と筆者が衝突した際に不備なくこちら側の言い分を主張するためのものであるからだ。
ブログを始める
要約
- これは技術記事でない
- 記事を書き始めることにした
- React記事多めになる
- 予防線は張ったので話半分で読んでくれ
- これも予防線である
- 再帰的だ
なぜ今になって書き始めたか
目的を簡単に纏めると、以下のようになる。1
それぞれ項目毎に詳細を述べる。
インプットの整理がしたい
これはまずもって大きい。実際に文章にすると知識が明確化するし、細部にまで目が届くようになる。
なおこの目的のみを追求したとき、記事を後から読み返すことは考えない。なぜならば、書いた時点で目的は達成されるからだ。筆者には、学生時代に張り切って見やすいノートを作った結果、その構成を考える過程で内容を全て覚えてしまい、それ以降ノートを一切参照しないという経験があった。つまるところ、この目的に偏重することすなわち、記憶することのみに熱中し、記事の資料としての価値を放棄することに他ならない。
インプットの整理をするのは重要だが、極論それならばメモ書きで十分だ。わざわざ記事に起こそうとしているのだから、それ以外にも目を向けるつもりでいる。
文字に書き出すと頭がスッキリする
これは上記のインプットの整理の副次的効果だが、それの二次要素とするには余りにも大きすぎる。頭がすっきりするというのは勉強の能率を上げ、かつインスピレーションの土壌とモチベーションを提供する。決して侮れない効果だ。
特に筆者はモチベーションさえあれば40時間程度ならずっと同じことをしていられるので、こういうメンタリティに属する作用も無視できない。
また思考を文字に書き出すというのは、ある意味で脳内の不要なキャッシュを明示的に削除する行為でもあると言える。人間の脳構造に明るくはないので断言こそ避けるが、私の場合文字にして書き出すとその思考を捨てることができる。これの効果は非常に芳しく、落ち込んだときや怒ったときなど、激情が迸っているときなどはよく文字に起こすことでメンタルコントロールに役立てたものだ。こういった例のように、文字に起こす行為は人間の脳にポジティブな効果を発揮するのではないか、というのが私の考えだ。
後から見返したい
個人的な面でいくと、後から見返すという行為の意味を最近になってようやく知った。いやなに、文字通りの意味は知っているが、後から見返さないといけないほど古い知識を使うタイミングが学生時代になかったのだ。
だが、残念なことに現在私が行っているプログラミングにおいて、半年前の自分の書いたコードを読むという行為は避けられない。そのために少し前から積極的にコメントを書くようにしているのだが、それだと即応的な面でしか補填できていないのである。もっと具体的に述べるのならば、人に教えられる程度の知識に昇華できていないということだ。ノウハウを貯めるのもいいが、個人の内部に累積させるには限界がある。そこで、ブログの記事にして情報を集積しようというのが私の今回の記事の執筆の動機なのであって、とどのつまりはこの項こそが私の主目的だったという訳である。
これからやりたいこと
要点は以下だ。2この最初に要点を連ねる手法も無粋のように感じるときがあるものの、これ以上の最適解を知らないのでよっこらよっこら従っていく。
技術記事の継続的執筆
結論から行くと、これは目標であり今々達成するつもりはない。なぜなら、ノウハウとは単純な一次関数のようにコンスタントに増えるものでなく、むしろ音の波形に近いものがあるからだ。3
だというのにアウトプットだけ続けようとしても無理難題が過ぎる。この目標はいずれ知識をストックできるような思考形態が育ってきた頃合いに達成しようと思う。
なお、現在はReactをフロントのベースにしたプロジェクトを進行させているので、必然的に記事の傾向はReactに寄ると思われる。
プロジェクトでの出来事と感想の記事
私は現在、ポートフォリオとして相互コード片レビューサイトを作成している。進捗率はといえば一割程度なので、まだまだ道のりは遠い。
バックエンド担当のたかし君（仮名）4が気合を入れてOauthっぽい仕組みを自力で実装してくれたので、ログインフォームの時点でかなりそれっぽい仕様が出来上がりつつある。また総合メインレビュアー兼フロントサブ担当のスナネコさん（仮名）5もCircleCIを組み上げ自動デプロイの整備までしてくれているので、フロントメイン担当のこちらとしても身が引き締まる思いだ。
そんな風に、プロジェクト途中であった細々としたことから盛大に困ったことまで、様々なことを雑記として残すのも記事の執筆の目的である。これは記憶として残す日記的意味合いもあるが、単純に完成したとき苦労したところを何も覚えておらず、人から聞かれたときに困るのを回避するためでもある。
予防線
今後は技術記事を書くといったが、ほぼ嘘だと思って読んでほしい。
参考にするかどうかは全て読者に委ね、こちらは一切の責を追わないことを前提条件として理解して頂けると有難い。
なお、また技術記事の先頭に貼る用の遠慮の塊ならぬ予防線の塊も記事として用意する予定だ。
終わりに
今回、VSCodeのvimコンフィグで書いてみたのだが、日本語入力とvimのキーコンフィグの相性が壊滅的に悪く、途中いらいらして投げだしそうになった。正直Meryとかのほうがいいかもしれない。だがそれでも私はVSCodeが好きなので使っていきたいとも思っている。好きすぎて頑張ってブログの色合いをVSCodeに近づけたぐらいであるし。
なお、結局のところ当ブログの主目的は自分本位なものなので、見栄えなどは気にしない。機能を使いこなしていないなどIT職が泣く、と言われそうなものだが、むしろIT職だからこそ学ぶコストを重要視しているという言い訳を残しておく。
というより、自分本位でない技術記事を書くならはてなブログよりQiitaや、最近のものだとzennなんかがよいのだろう。そこをあえてはてなブログにしている理由は、個人ブログであるという体裁が私にとって非常に都合が良かったからである。私だって人間である以上感情はあるので、Qiitaに何か記事を投稿してポエム乙とかコメントに書かれると泣いてしまう。
ひとまず、次の記事はプロジェクトの現状をつらつらと書いてみる予定だ。見つけたUtilなんかもいずれ技術記事として出すつもりではある。
ところで、ブログを始めて最初の記事のタイトルが「ブログを始める」であるの、情報量が何一つ増えていなくて馬鹿らしい感じがする。もう少しセンスと呼ばれる類の才能が欲しいものだ。
