2週間くらいで溜まった知見をドキュメントにしてみた話

公開日: 2025-07-23 作成者: whatacotton

どうもこんにちは、whatacotton と言います。Ultra-Coins の学生代表をさせていただいています。(2025/05/21 時点)

今回は記念すべき初記事ということで、アウトプットの大切さを書きたいなと思います。

知見は広めた方が良い

私は今年度、組み込みキャンパス OJT(COJT)という通年で行われるプログラムを受けており、その中でもハードウェアコースという Field Programmable Gate Array(FPGA) と呼ばれる、再構成可能なチップを用いた実験を行うコースを受講しています。

元々 FPGA に関してはある程度触れていたのですが今回本格的に触れるということで、開発に CI/CD 的な自動化システムを使用したいと考えるようになりました。というのも、FPGA ベンダが提供する EDA ツールは基本的に GUI で使うことが前提のため、そもそも自動化と相性が悪いからです。

実験で使用する Vivado という EDA ツールは、Tcl というスクリプト言語に対応していると調べていくうちにわかりました。そのためなんとか Tcl を使いこなして自動化できないかということになり、たくさん資料を漁った結果、なんとか整備することができました。

最初はこのスクリプトを秘伝のタレ的な感じで自分の中で使っていこうと思っていたのですが、環境を整えてからしばらく経ち、この環境をもっとたくさんの人が使えるようにすることで助かる人がいるのではないかと思うようになりました。

そこでドキュメントを作り始めることにしました。

ちなみに公開したドキュメントは以下のリンクで公開しています。

今回、Cloudflare Pages を用いて公開することにしました。

理由としては、

といった点があります。セルフホストでも良かったのですが、あまり保守に時間が割けない上に、とりあえず雑に公開したかったのでこの選択をとりました。

ドキュメントをホストする CMS の選定も少し時間がかかりましたが、結局 Docusaurus にしました。Docusaurus にしたのは、かっこいいデザインと TypeScript で書かれていたからです。また、あまり独自の記法がなさそうだったのも理由です。

制作期間は 2.5 日くらいです。環境を整えるためには 2 週間程度かかりましたが、そのあとは自分の書きたいことをつらつらと書き連ねていくだけだったので、走り書きのようになってしまいましたが、かなり短期間で書ききれたと思います。

自分の書いた文章にあまり自信がなかったので、ツイートする前に 1 週間くらい色々な人に相談して内容を確認してもらいました。文章の添削を主にやってもらいました。

確認・添削していただいた皆様、ありがとうございました。

だいぶ色々な人に見てもらっているみたいで嬉しいです。また自分のドキュメントを読んで、コードの冗長さを教えてくれる人もいたのでやはり公開することは大事だなと思いました。

いかがだったでしょうか。また新しい知見を手に入れたらまたドキュメントを書いてみようと思います。皆さんもまとまった知見を手に入れたらドキュメントを書いてみるのはどうでしょうか。