こんにちは。はこだてたろうです。
GWも最終日となりました。東京は昨日と打って変わって曇り空です。
さて、プラプラ！シリーズへのモチベーションがふつふつと湧いてきています。
とはいえ、あんまり気合いを入れてやりすぎるとまた続かなくなってしまいますので、持続可能な形で進めていきたいと考えています。
Border7シリーズを少しやってみて問題というか、大変だなと思ったのが以下の点でした。
- 技術的な裏を取ること
- 各回で取り上げた技術の解説
- 設計書のメンテナンス
１つ目の「技術的な裏を取ること」は、このような技術系の発信を行うのであれば避けて通れないことなので、この先も向き合い続けていかなければなりません。
２つ目の「各回で取り上げた技術の解説」についても、発信をする以上は読者さんに伝わるように改善を続けていかなければなりません。
つまり、上２つはこの活動を続けていく上で必要なことで、大変だからと捨ててはいけないことになります。
でも、それが足かせになって、発信そのものが滞ってしまっては元も子もありません。
これについては発信の仕方を調整して、いい距離感で取り組んでいけるよう今後も改善を重ねていきたいと思います。
そして３つ目は、今回の記事で焦点を当てたい「設計書のメンテナンス」です。
現在、プロプラ！シリーズの設計書は、各コンポーネントや各関数の jsDoc に記載する形で作成しています。
対象の関数のすぐ近くに設計書がある、ということは読者さんにとってわかりやすい（はず）と考えており、このような形にしているのですが、私にとってはなかなかやりづらかったです。
訂正したいものがあったら、そのままファイルを訂正してコミットしてしまえばいいのですが、ブランチを分けているのでそう簡単にはいきません。
出題用にプログラムを穴抜き状態にしているブランチと、元となる解答用のブランチがあり、両者に訂正した変更を適用しなければなりません。
さらに各回から始められるように、それまでの内容を実装したブランチも用意しているのでもうごっちゃごちゃです(^_^;
これはもうやってられんなということで設計書の書き方を考えます。
まずは設計書を jsDoc に書くのはやめて、別ファイルに書かないとですね。
それだけで上で挙げたような問題はおそらく解決すると思います。
別ファイルに書くならフォーマットもある程度自由になるので、取り組みやすいものを選びたいですね。
いまのところマークダウンを採用したいと考えています。
著者にっとても読者さんにとっても持続可能なコンテンツを作っていきたいと思う今日このごろでした。
コメント