あったらいいなと思って作っているMarkdown絡みのツールについて書きます。
作ってるのは、Markdown方言
Markdownって簡単に書けるのが気楽でいいですよね！
ただその反面、プログラマブルではないですよね。
あと、どうしても「これ！」といったMarkdownエディタ(ビューア)に出会えないですよね。
じゃあincludeとか埋め込み文字列に対応した方言作って、それを使えるエディタつくろうぜ！
と思ったのが 昨日です。
ドキュメント管理という闇
そもそも、みなさんは開発者向けのドキュメント管理、どうしていますか？
私は今のPJで構成管理者をさせてもらっているのですが、ドキュメント類はなるべくGitbucketに乗っけさせてもらっています。
ドキュメント:
- 環境構築手順
- ソースのバージョンが新しくなった時テスターさんに実施してもらう手順
- 新規着任した構成管理者向けのリリース手順
- etc...
当然ですがWebで見れて、Markdownで簡単に書けるのでそれ自体は悪くないです。
ただこういうドキュメントって、最初に書く時はその時の最新手順やスクリプトをサクッと誰かに伝えるために書くのですが、激しく変わっていく手順に追いつけずに結局すぐに管理できない古い情報が入り混じったボロボロの情報のカタマリになりませんか？
シェルスクリプト化し終わった部分がドキュメントとして残ってたり、重複してたり不要になった手順が混じったり…。
少なくとも私はなってます。
手順書的なドキュメントのつらさ
新規着任したエンジニアさんやテスターさんには、システム要件を学んでもらいながら仕事をしてもらったりします。
そういう時は「上から順にバーっと実行すればとりあえずうまくいくよ」という手順書をまとめておいてそれを渡します。
ただ、それをドキュメント化しようとするとちょっとしんどい問題に出くわします。
それは、「ちょっとずつ異なる手順を何度も繰り返す」みたいな指示が必要な時です。
たとえば
- Aをする。URLはexample.com/A
- Bをする
- Cをする
- 1~3を繰り返す。 ただしURLは変わる。また、Cの時だけは追加でC'という手順も行う。
みたいなことをお願いしなきゃいけない時、これをそのまま書くとドキュメントの読みやすさは非常に残念な感じになります。何度も上に戻らなきゃいけなくて無駄に脳内メモリを食う作業になります。
じゃあベタ書きで手順1~9を書くかと言われると、若干2年弱の私でさえ「それはプログラマの仕事ではない…」と胸の奥がざわめきます。
プログラマブルなMarkdown
そこで作ってるのが markinc です。名前はもう決まってます。
できたいこと
- 外部化したテンプレート用Markdownファイルの読み込み
- テンプレートへの文字列埋め込み
- Markdownエディタ化
- テンプレート、文字列埋め込みを解決したMarkdownを出力
今ポチポチ作ってます。
advent calendarで成果を発表できないのが残念ですが…続報をお待ちください！
明日からのtis advent calendarをお楽しみに！
明日はenterprise1024氏です。
「The first step to become Arch-Excelist」ってありますし、Excelネタっぽいですね！
いやあ、SIer感漂ってますね！
その後にも、人工知能やインフラのコード化、機械学習…アツいテーマが目白押しです。
お楽しみに。私も楽しみです。