聞こえないJavaエンジニアが適当に書き連ねていく

つらつらとメモしたり日頃の溜まっている想いを吐き出す場所です。

プロジェクトの各種ドキュメントをExcelではなくMarkdownで作ってみた

これは何

プロジェクトの知見共有や手順書を共有する時に、Excelではなくてmarkdownで書いたWebsiteを使ったことの振り返り。

注意

Excelを全く使わなかったのではなく、主な資料をExcelではなくてWebsiteにした。補助資料をExcelで作ったものもある。

なぜExcelにしなかったのか

過去のプロジェクト経験を基にExcelを使うことのメリットとデメリットを比較した時、Excel以外の方法を試してみる価値はあると考えた。

Excelのメリット

  • 画像の貼り付けや吹き出しの付与が簡単
  • 文字の装飾が簡単
  • 印刷することを想定しなければ、見た目を整えるのが非常に楽

Excelのデメリット

  • ファイルをどこに置いてあるか探しにくい
  • ファイル内部の文言検索がやりにくい
  • 画像を大量に貼り付けるとファイルサイズが大きくなる
  • 修正した時、差分の確認がほぼ不可能

Markdownで資料を作る

選定

以前から個人的な資料はMarkdownやAsciidocで書いていた。そのため、どちらかを使って書くのが楽なのではと考え、プラグインや公開手順の楽さ、第三者がすんなり書けそうな記法、などを考慮しながら調査した。

結果、Markdownで書けるMkDocsが一番楽に導入出来て、生成されるWebsiteも見やすそうだったのでこれに決定。

公開環境

プロジェクトの資料のため、社外の人が見られる環境に公開は出来ない。そのため、ページを開く際に何らかの認証が必要だった。

2020/9/2の時点では、GitLabのpages機能も公開範囲を制御出来るようになっているが、プロジェクト開始の時点ではまだその機能が無かったのでGitlabのpages機能を使うことは断念。 調べていたら、Herokuの無料枠で公開する方法があり、かつ、basic認証も使えるとのことだったのでherokuに決定。

herokuへの公開方法はgitだったので、markdown形式で書いたファイルをビルドしてhtml形式に変換し、herokuの専用リポジトリにpushすると公開される。

プロジェクトネットワーク内にサーバーを立ててもよかったのだが、プロジェクト開始当初は協力会社の方が社外で作業する可能性があったので内部にサーバーは立てなかった。

プロジェクトが終わると見る人が激減するのでherokuでの公開は止めて、社内サーバーに改めてドキュメント公開サーバーを構築しようと考えている。

執筆環境

執筆陣

本当は全員で修正できるようにしたかったが、集まったメンバーが若手ばかりで頼める状況になかったため、ブログ主と協力会社の方、1名の2人で書いた。

しかし、協力会社の方もだんだん開発作業に追われて忙しくなり、後半はブログ主しか書いていない状況になってしまった。

書いたドキュメント

大きく分けると以下の4カテゴリになる。 このカテゴリの下にさらに細かくページが作られている。

  • 環境構成
  • 開発環境の構築手順
  • 開発の手引き
  • 技術検証で得た知識
    • 個人的なメモに近いものもあったが、後々聞かれたときに説明が楽だった。

実際にやってみた感想

執筆について

markdownで書くのは楽しかったが、画像を使った時の見た目の調整に悩まされることがあった。これはExcelで作った資料に慣れ過ぎたせいで、同じような見た目を求めてしまったというのもある。 markdownで書くときは、レイアウトにはそれなりの割り切りが必要。

執筆出来る人を育てられなかったのは反省点でもあるが、集まったメンバーを見ると無理強い出来なかったのも事実。 今回のプロジェクト経験者が他のプロジェクトに行ったときに、そういや前のプロジェクトではなんかWebsiteで公開してたな、どうやっていたんだろうと気にして調べてくれるか、聞いてくれることを期待している。

知見共有について

開発環境の構築をWebsite化したことで、プロジェクトに参画したら最初はブラウザを起動してページを開く、に出来たのはかなり楽だった。

これがもし、Excelで作っていたら、まずExcelを渡すか、ファイル共有クライアントのダウンロードから始めないといけなくて最初の説明が煩雑になっていた。

開発時も、Websiteに検索機能があったのでわからないときは検索機能を使って検索してもらえた。Excelよりは探しやすかったのではないかと思う。

また、他のプロジェクトで技術の質問があったときに重いExcelを渡すのではなく、WebsiteのURLを送るだけで済んだのも楽だった。

次にやるとしたら

次の新規開発プロジェクトに参画する機会があるのかわからないが、もし、参画する機会があり、ドキュメント整備をする機会があれば検討したい事項は以下。

ドキュメントのデプロイ先

今回はherokuを使ったが、herokuは一定時間アクセスが無いとサーバーが止まる。そのため、サーバーが止まった後に初回アクセスすると画面が開くのが遅かった。 これはストレスだったので、次はherokuを使う可能性は低いと思う。 これは単純に用途の問題であり、herokuのサービスそのものは悪くない。

ではどこにデプロイするか、だが、Gitlabのpagesか、プロジェクト内ネットワークのどちらかであろうと思う。 会社やプロジェクトでGithubを使うようであれば、Githubのpages機能も選択肢に入ってくる。

執筆環境

今回はmarkdownだったが、asciidocも改めて検討したい。asciidocの方が表現の幅が広く感じる。

執筆陣

これはプロジェクトメンバーにもよるので一概には言えないが、自分だけが書くのではなく、みんなでドキュメントを育てていく環境を作りたい。

まとめ

いつか、設計書も脱Excelしたい。いつかできるだろうか。