2020年の12月に開催されたCLI 専門支部の勉強会「手順書ないと」に参加したのでそのレポートを書いてみる。
波田野さんの勉強会はいつも得るものが多く、
個人的には「参加し ないと、損する」レベルだと思ってる（割とガチ）。
今回の『手順書ないと』も、
普段の勉強会とは少し方向性は違うものの、とても興味深い内容だった。
よい手順書の作り方
- ドキュメントを多くの目に晒す
- ドキュメントを構造化する
- ドキュメントの構造を検証する
テクニック的な部分はさておき、「多くの目に晒す」という
なんとも基本的なアプローチに思わずハッとさせられた。
ドキュメントは自分だけが見るものではないので、
他人がどう理解するか、という点は極めて重要。
そして多くの目に晒すために、勉強会を大量に開催されているのはシンプルにすごい。
173回のハンズオンとか、はっきり言ってどうかしてる。（もちろん良い意味でｗ）
CLI 専門支部の洗練されたハンズオン手順書は、
多くの目に晒され、ブラッシュアップを繰り返すことで出来上がっている、
そう思うと納得感がある。
（173回はハードルが高いがｗ）
頑張って多くの目に晒すべし！
手順書は機械と協力して書く
「人が書く」と「機械に書かせる」を意識的に分離して、
人にしかかけない部分だけを書くことを意識するべし。
「ドキュメントの全てを人が書く」という観念からの脱却が必要
手順書の ”自動生成” によるメリット
- 論理的な矛盾・不整合を排除しやすい
- 論理的な正確さ（目的適合性）
- 事前条件、事後条件の妥当性（ホーア理論）
- 論理的な整合性
- きれいなOutputのために、Inputをきれいにする
命名規則・名前空間は大事
全エンジニアが意識すべきこと
最小の工数と時間で最大の効果が得られる方法を模索するべし。
「工数と時間」より「格好いい」とか「流行り」を重視するケースは非常に多い。
「Unixコマンド」は学習コストに対して得られる効果が大きい。
加えて、長く使えるのでコスパがよい！
Sphinx というイケてるTOOL
AWC CLI 公式リファレンスでも利用されている、ドキュメントビルダー。
主な重要な機能は以下の通り。
まだ使ったことがないので早めに手を出したい。
- インクルード
- include（reSTファイルをインクルードする）
- literalinclude（ソースコードをインクルードする）
- csv-table（CSVファイルをインクルードする）
- 置換
- ドキュメント内の特定の場所を置換して出力される
- タイトル表示
- 子ドキュメントやリンク先のドキュメントタイトルをリンクに埋め込むことができる
Sphinx 導入、その前に。
Sphinx をより効率的に使いこなすために、次の知識を身につけておく必要がある。
個人的にはシェルやsed コマンドの部分に不安があるので、改めて基本ダイジやなと感じた。
- AWSコマンド
- シェル
- 標準出力のファイルへのリダイレクト
- ヒアドキュメント
- echo / cat コマンド
- sed コマンド
Linux (Unix) の基礎はSphinx に関係なく必要なので、
これを機にマスターしていこうと思い、LPIC の教科書を入手してみた。学ぼう。
sed で扱いやすくするという意味でも
やっぱり「命名規則・名前空間は大事」
名前空間を制するものは、ゲームを制す(違)
CLI 専門支部で ”しっくりくる” 理由
AWS 入門してまもなく、学習方法に悩んでいたところに
私はCLI専門支部に出会ったわけですが、
「これや！ここで勉強させてもらお！！」と思って、今でも楽しく学ばせていただいている。
AWS を学習するにあたって、
CLI専門支部での学びが捗る（しっくりくる）理由が、今回の勉強会で見えてきた気がする。
資料面のポイントを書き出すと、ざっくり次のような感じ。
ただ、波田野さんの雑談も楽しみにしている私としては、それ以外の魅力による”捗り”も大きいように思える。（波田野さんの話は入ってくる感。ｗ）
- 構造化されている
- 一定のリズムで進めることができる
- そこで学ぶ「新しいこと(メイントピック)」に集中できる
- 何の手順がどれか、目次を見れば一発でわかる（復習もしやすい）
- 迷子になりにくい
- 低コンテキスト化により、個別手順(タスク)単位で独立した構成になっている
- タスク単位で独立しているので、基本的に迷子にならない
- 仕事で活かせる
- 構造化のリズムは、自分が手順書を作成する際に参考になる
- 各手順は、CLI手順書のTips として利用(応用)することができる
まとめ
- 手順書作ったら多くの目に晒してブラッシュアップ
- 手順書作成は機械との分業制にする
- Sphinx は構造化の強い味方 (名前空間を制するものは!)
- Linux (Unix) 基礎はダイジ
- CLI専門支部の魅力には理由がある (ファン度がUPした。ｗ)
Sphinx を利用したデモは、
正直いうと理解が追いつかない部分（ファイル作成などをどのように機械化/効率化しているのか、どうメリットがあるのか）もあった。
いきなり波田野さんレベルを目指すのはハードルが高いなと思いつつ、逆に魔法使いみたいなことができることを知ったので、あとは自分でやってみるだけ。ｗ
自分に足りない部分（シェル、sed コマンド）は分かったので、
一つずつクリアしていき、前進を続けたい。
最後まで読んでいただきありがとうございました。
