見出し画像

wikiの執筆を効率化する仕組み

iGEM-Waseda

この記事は、アドベントカレンダー「iGEM･Synthetic biology(合成生物学)･Japan Advent Calendar 2024」の5日目の記事です。

はじめに

はじめまして、iGEM-Wasedaのbishopfuncです。本年度はシミュレーション班とwiki班のリーダーを担当しました。

この記事では、wikiの炎上を回避するために、原稿を効率的にHTMLに変換するシステムを構築した話を紹介します。

iGEMのwikiは初年度参加チームにとって、1つの沼りポイントだと思います。この作業は皆さんが想像する何倍もの時間を要します。wikiのトラブルが原因で成果を十分にアピールできなかったという話もよく耳にします。

この記事では技術的な内容が多くなりますが、技術に詳しくない方にも、iGEMにおけるwikiの課題やこのシステム開発の意思決定の背景を知っていただければ幸いです。

モチベーション

皆さんのチームでは、原稿をwikiにアップロードする作業はどのように行っていますか？おそらく、多くのチームがwiki班の気合いに頼っているのではないでしょうか。

2年前のiGEM-Wasedaもそのような方法を採用しており、僕メイン+2人のメンバーでなんとか気合いでやっていました。その年はなんとかなったのですが、この方法にはいくつか問題があると感じました。

  1. 原稿がWordで書かれているため、手作業でHTMLに変換する必要があり、膨大な時間がかかります。また、変換時にミスが発生しやすい。

  2. 誤字脱字を修正する際、HTML内から該当箇所を探す手間が大きい。

  3. ※事前にルールを決めていなかったため、執筆者ごとに階層構造や書き方が異なり、どのHTML構造に変換すべきか迷うことが多々ありました。そのため、執筆者の意図を推測しながら作業する必要がある。

  4. ""や''など記号がHTMLではエラーの原因になるため一部の記号は&quot;や&apos;に変換する必要がある。太字や斜体はで<b></b>や<i></i>で囲う必要がある。

  5. 原稿がなかなか完成せず、上述の問題がwiki freezeの直前1週間に集中してしまう。

※参考文献や図番号に関する議論は行われていましたが、原稿をHTMLに反映する手間は想定されていませんでした。

その年のJamboree後、iGEM Japan Meetupに参加した際、iGEM TokyoTechさんがmarkdownをHTMLに自動変換する仕組みを導入している事例を聞きました。この話に触発され、次こそは自動化しようという決意を固めました。

さらに、記法の未統一やスケジュール管理の甘さから、wiki班が単なる専門業者的な役割にとどまらず、wiki執筆全体のマネジメントにも積極的に関わるべきだと強く感じるようになりました。

キックオフ

2024年の春新歓を終えた時期に、iGEM-Waseda内でそこそこフロントエンドを実装できるメンバーが僕含め3人いました。これでシステム化に必要な開発メンバーは十分に揃っていました。(そうできるように僕が頑張って2人勧誘しました。) 4月頃に行われたキックオフミーティングでは、システム化の方針を決定する前に、他の選択肢も含めて議論しました。当時検討した選択肢は以下の3つです。

  1. 既存のメンバ3人で気合いでコピペする

  2. 簡単なHTMLを読めるメンバーを増やして、分担する

  3. 時間をかけてシステム化する

1つ目の選択肢は、2人のメンバーが※シミュレーション班を兼任しているため、wiki freeze直前の作業時間を確保できないことから断念されました。
その時期は、model関連のプログラムの実装や、wiki原稿の執筆などで手一杯になることが予想されたためです。また、非効率なコピペ作業に時間を割くよりも、一つでも多くの成果を作成・ブラッシュアップすることが重要だと考えました。この予測は結果的に的中しました。

※ iGEM-Wasedaではdryチームがシミュレーション班と数理生物班に分かれています。数理生物班は数学が得意な人たちで、シミュレーション班はプログラミングが得意な人たち、みたいな分け方になっています。そう考えると、wiki班がシミュレーション班を兼任するのは自然ですね()。

2つ目の選択肢は、教育コストをかけられるほど余裕がなかったらため、断念しました。簡単なHTMLならすぐに習得できるのですが、wikiはコンポーネント指向のReactなどのフレームワークを利用することが予想されたことと、Gitブランチの運用などに関しても教育が必要だと考えました。特にwiki freeze直前の切羽詰まった状況で、初心者が「破壊的コミット」をしてしまうリスクは非常に高いと感じました。万が一、そうしたトラブルが発生すると、bronze medalを逃してしまう可能性もあります。また、教育のためには結局はシミュレーション班から人を引き抜くことになり、そちらの作業時間が減るのも問題だと考えました。

※ 「破壊的コミット」は僕の造語ですが、レンダリングが上手くできてないのにpushしてしまうような状況のことです。wiki freeze直前はビルドがスタックしているため、「破壊的コミット」に気づくのが遅れたり、修正しても反映に時間がかったりします。その場合、wiki freeze時に上手くレンダリングできてない画面が永遠に残ってしまうようなトラブルが発生します。

3つ目のシステム化には、メンバーにmarkdownなどの記法を覚えてもらう必要があり、事前にシステムを開発するための時間も必要です。しかし、その分wiki freeze直前の作業は大幅に軽減されると見込みました。また、長期的な視点で見ても、システム化は最も合理的な選択肢と考えられました。その結果、満場一致でこの方針に決定しました。

要件定義

次に行ったのは、必要な要件の洗い出しです。単にmarkdownをHTMLに変換する仕組みは既存のライブラリでできるのですが、全体のワークフローを考えずmarkdownだけ導入するとメンバーの学習コストや管理コストだけが増えてしまいます。そのため、wiki執筆のワークフロー全体を最適化することを目指しました。

プレビューサイト

最初に考えたのは、効率化を図る上での理想的な状態です。それは、執筆者が原稿を提出した時点で、wiki班が何の修正も加えることなく、wikiに反映できることです。これまでの作業では、以下の点を毎回確認する必要がありました。

  • 正しくレンダリングされているか

  • 執筆者の意図通りになっているか

  • 画像のサイズや配置が適切か

こうした確認作業を減らすため、markdown用のプレビューサイトを用意する必要があると考えました。この仕組みにより、原稿の最終チェックは執筆者自身に任せることができ、wiki班の負担を大幅に軽減しました。

Markdown Parser

次の課題は、iGEMのwikiが求める機能をすべて標準的なmarkdownだけで実現するのが難しいことでした。例えば、以下のような機能が必要です。

  • Tex記法

  • Code Block

  • 画像キャプションとサイズ設定

  • 脚注

この問題を解決するため、リッチな機能を備えた上で独自記法を拡張できるmarkdown parserが必要だと判断しました。

Markdown Editor

markdownを採用するなら、それに特化したエディターも必要になります。特にiGEMのwikiでは複数回のレビューと修正を行うため、エディターには同時編集、バージョン管理、コメントなどの機能を持つ必要がありました。

これらの機能を持つmarkdownエディターと、プレビューサイトを一体化させたシステムを開発することにしました。そして、そのmarkdownエディターとwikiの両方にmarkdown parserを導入するような実装にしようと考えました。

実装

プレビューサイト

デフォルトでキャッシュ、コピー、ペースト、REDO、UNDO機能を備えているEasyMDEを利用し、Vercelを使ってホスティングしました。

Markdown Parsar

プログラミング記事サイトのzennが採用しているzenn-markdown-htmlを利用しました。有難いことにその記法を使えるのレポジトリを公開しているため、これをforkして拡張の記法を追加しました。forkしたレポジトリはこちらです。

また、使用時には、wikiのpackage.jsonに以下のような記述をします。

  "dependencies": {
    "zenn-markdown-html": "https://gitpkg.now.sh/iGEM-Waseda/zenn-editor/packages/zenn-markdown-html?canary"
  }

zenn-markdown-htmlに元からある機能：

  • Texの数式

  • 画像のサイズ

  • TOC(目次)を自動生成

  • トグル(文章を折りたたむ)

  • コードブロック

自分で追加・変更した機能：

  • 脚注の参考文献の自動採番

  • 2つの要素を並列に並べるブロック

  • 画像のキャプションの設定

Markdown Editor

当初は独自のMarkdownエディターを開発する予定でしたが、wiki班のメンバーが1人減ったことで、時間的余裕がなくなり、開発を断念しました。その代わりに、Google DocsをMarkdownエディターとして利用することにしました。また、1つの案として、Gitlabのオンラインエディター機能も考えたのですが、Gitの学習コストと「破壊的コミット」のリスクがあるため、断念しました。

Google Docsは以下の理由のよって採用されました。

  • 見出し、太字、斜体など、基本的な記法をサポート。

  • バージョン管理、同時編集やコメント機能が利用可能

  • Google Docsの記法をMarkdownに変換可能。

ただし、Google Docsの記法で対応できない部分（標準的なmarkdown記法や拡張markdown記法）については、markdown記法をベタ書きする形を取りました。また、markdownでも対応できない、PDFや動画のiframeなどはclassを付けたHTMLをベタ書きしました。これらのに記法については種類を制限し、詳細なガイドラインを作成しました。

運用

実際の運用では以下のフローに従いました。

  1. 通常の記法で文章を作成し、数回レビューを行う。

  2. 記法のガイドラインに従って、原稿を直す。

  3. 原稿をmarkdownでダウロードし、画面崩れがないことをプレビューで確認。

  4. その時点でversionを固定、編集はコピーして別versionをつける（model v3を修正依頼したらもう編集しない）。

  5. Slackでwiki班に修正を依頼する。

  6. wiki班はローカル環境で画面崩れがないことを確認し、pushする。

運用していると、いくつか当初想定しなかった問題点が発生しました。

  • 記法のガイドラインに関するアナウンスが遅れたため、チームメンバーが理解できてない部分があった。

  • Google Docs記法にある記法を使えず、あえて拡張markdown記法を使うというようには、直感に反するルールがありました。例えば、画像の挿入や脚注がそれに該当する。

  • Google Docs単体では拡張記法のmarkdownをレンダリングできないため、一度普通のwordに書いて、その後記法に反映するような二度手間になってしまう。

  • Google Docsのからmarkdownに変換する際に"*_{}[]()#+-.!=<>\$"などの記号の前に"\"が増える。

  • "\"が増えたことによってTexが綺麗にレンダリングされない。

  • 一度markdownに変換すると、レビューがしにくい。

  • Human Practice、Engineering、Modelページが思ったより長くなってしまい、見やすくするための急遽UIを作成する必要があった。

改善点

色々問題もありつつも、なんとか運用しwikiを完成させることができました。結局人手で無理やり回してる部分もありますが、多少は効率化できたかと思います。僕は今回でiGEMを引退しますが、もし来年度もやると仮定するなら、以下の改善点があると思いました。

文章が長いページは別でUIを実装しよう
自分の認識が少し甘かったのですが、ModelなどのGold要件や、Human Practice、EngineeringなどのSilver要件のページは文章量が多くなりがちで、長すぎると審査員きちんと評価してもらえないリスクがあります。そのため、早い時期から、担当者と密にコミュニケーションをとり、それをカバーするようなUIを設計すべきでした。

ちゃんとMarkdown Editorを作ろう
やっぱりGoogle DocsにMarkdownをベタ書きするのはやめしょう。
現代だったらOSSをちょっと変えるだけ対応できそうです。あまりちゃんと調べてないけど、これとか良さそうです。

Google DocsからGithub/Gitlabに直接pushしよう
こういう拡張機能を使えばコピペにかかる作業も効率化できそうです。ローカルで確認しないでpushするのは怖いけど、CI/CDやブランチを上手く管理すればなんとかできそうです。例えば、以下のフローが考えられます。

  • 記事をGitLabの特定ブランチにpushする

  • wiki班がローカル環境で内容を確認する

  • 確認後、wiki班がブランチをマージする

別の方法

同じモチベーションで別のアプローチも考えられます。

Google Docsからclass付きのHTMLに直接落とす
さきほど紹介した拡張機能には、styleやclass付きのHTMLに変換する機能も含まれているようです。これにより、Markdownの特殊な記法を使わずに、Google Docsの機能だけで画像のサイズを調整できるため、プレビューサイトを利用せずにGoogle Docs上で画面が崩れていないか確認してもらうだけで済むようになりそうです。

  • Astro/remark.jsを使う
    フロントエンドフレームワークAstroはデフォルトの機能でmarkdownをサポートしています。Japan-Unitedのwiki担当が昨年のアドカレでその記事に書いています。やってることフレームワークが違うだけで、ほぼ同じですね。zenn-markdown-htmlがmarkdown-itを使っているに対して、AstroだとmarkdownとHTMLの変換にremark.jsを使ってるらしいです。markdown記法を拡張したい場合、remark.jsを弄れば良さそうですね。軽く見た感じ、そういうサンプルコードは割とネットにあります。

まとめ

最初は原稿を自動的にHTMLを変換する仕組みを考えるつもりでしたが、結果として執筆全体のワークフローをマネジメントすることになりました。

まだ改善の余地はありますが、自分なりにwikiの課題やそれを解決するシステム、そしてその運用方法について考えました。

このシステムが最適な解決策とは限りませんが、wikiの効率化は多くのチームに共通する課題だと思います。iGEM Japan Communityなどでこうした仕組みを共同で開発・管理すれば、未来のiGEMerたちにとって大きな助けになるのではないでしょうか。

また、iGEMにおけるwikiシステムは、2022年以降ますます便利になっています。私が把握している限りでは、以下のような取り組みが進められています。

  • iGEM2022 GitLabへの移行

  • iGEM2024 React/Markdown/HTMLのテンプレートから初期設定を選択可能

もしかしたら、近い将来には、こういったシステムを自作せずとも、公式からリッチなmarkdown記法が提供されるかもしれません。

最後まで読んでいただきありがとうございました。


いいなと思ったら応援しよう！