プロジェクトの各種ドキュメントを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での公開は止めて、社内サーバーに改めてドキュメント公開サーバーを構築しようと考えている。
執筆環境
- markdownエディタ
- Windowsの画面キャプチャ機能
- 画面編集ツール
- 吹き出しや枠囲みなど装飾したいときに使った
- iPhotoDrawが使いやすかった。
- Vector 新着ソフトレビュー 「iPhotoDraw」 - テキストや矢印、吹き出しなどの豊富なオブジェクトを使い、簡単な操作で画像に“注釈”を追加できる
- コマンドプロンプト
- gitクライアント
- herokuに反映させるために必要
- mkdocsをビルドするために必要な各種設定
執筆陣
本当は全員で修正できるようにしたかったが、集まったメンバーが若手ばかりで頼める状況になかったため、ブログ主と協力会社の方、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したい。いつかできるだろうか。
先日遭遇した謎のUnsatisfiedLinkErrorと解決について感じたこと
これは何
AdoptOpenJDK 11 を使った開発のテストをしているときに遭遇した謎のエラーと解決についてまとめたもの。
環境
IBM AIX 7.2 + AdoptOpenJDK 11 OpenJ9版
何が起きたか
JavaバッチでPDF作成処理を行おうとしたところ、下記エラーが出た。
yyyy/mm/dd hh:mm:ss.SSS [main] ERROR o.s.batch.core.step.AbstractStep - Encountered an error executing step HogeStep in job Hoge java.lang.UnsatisfiedLinkError: fontmanager (Not found in com.ibm.oti.vm.bootstrap.library.path) at java.base/java.lang.ClassLoader.loadLibraryWithPath(ClassLoader.java:1678) at java.base/java.lang.ClassLoader.loadLibraryWithClassLoader(ClassLoader.java:1643) at java.base/java.lang.System.loadLibrary(System.java:559) at java.desktop/sun.font.FontManagerNativeLibrary$1.run(FontManagerNativeLibrary.java:57) at java.base/java.security.AccessController.doPrivileged(AccessController.java:647) at java.desktop/sun.font.FontManagerNativeLibrary.<clinit>(FontManagerNativeLibrary.java:32) at java.desktop/sun.font.SunFontManager$1.run(SunFontManager.java:270) at java.base/java.security.AccessController.doPrivileged(AccessController.java:647) at java.desktop/sun.font.SunFontManager.<clinit>(SunFontManager.java:266) at java.base/java.lang.Class.forNameImpl(Native Method) at java.base/java.lang.Class.forName(Class.java:409) at java.desktop/sun.font.FontManagerFactory$1.run(FontManagerFactory.java:82) at java.base/java.security.AccessController.doPrivileged(AccessController.java:647)
ちなみに、落ちるサーバーで動かす前に別のAIXサーバーで動かしたときはPDF作成処理は正常に動いている。
手がかり
エラーメッセージ、java.lang.UnsatisfiedLinkError: fontmanager (Not found in com.ibm.oti.vm.bootstrap.library.path)
でググったら
下記issueがヒットした。
AIX builds have a dependency on libgcc_s.a for GUI apps · Issue #207 · AdoptOpenJDK/openjdk-build
Although most operations work ok without the GNU runtime library, it would appear that libfontmanager.so is built with a dependency on libgcc_s.a. The result of this is that any GUI application will fail unless the libgcc package is installed on the box and added to the LIBPATH. This appears to affect all versions of the AdoptOpenJDK builds. IBM's AIX java does not have this dependency. I believe it's due to the libfreetype dependency. When the freetype2 package is installed through IBM's version of yum for AIX, a symlink /usr/lib/libfreetype.a is created to /opt/freeware/lib, so that is found correctly, however for the libgcc package, there is no such symlink so it is not in the default search PATH and LIBPATH has to be set to include /opt/freeware/lib64 for GUI apps to work. I'm not sure if there's any obvious way around this, but I'm opening this issue to at least have it documented for now.
AIX版freetype2
を入れるか、/opt/freeware/lib64
を含むようにLIBPATH
を設定することで回避できる、と書いてある。
今回取った対応
正常に動いているサーバーにfreetype2
が入っていたので、それに合わせてAIX版freetype2
を入れることでエラーを回避した。
ただ、PDF作成処理でまた別のエラーが出たので、最終的には以下をインストールしている。
- freetype2
- fontconfig
- expat
AIX Toolbox for Linux Applications - Downloads alphaからダウンロード出来る。
問い合わせなどについて
動く環境と動かない環境があるということは環境の問題ではないかと推測。
AIXに対するサポート契約は結んでいたため、AIX窓口に問い合わせたところ、OpenJDK
に関する質問はこの窓口ではサポート対象外と言われてしまった。
(違う契約を結ぶ必要があった)
サポート契約については色々大人の事情もあるため、サポート対象外といわれたことについてはやむを得ないと思う。
感じたこと
Java開発を行う時、OpenJDK
を使うときはベンダーのサポートがほぼ受けられないのでネットでの情報収集が非常に大事になってくる。
特に、エラー情報についてはなかなかズバリの情報があるとは限らないため、要注意。
今回はたまたま、AdoptOpenJDKの開発者が注意喚起でissueを起票してくれていたおかげでたどり着くことが出来たが、 もし、issueがあがっていなかったら解決できていなかったかもしれない。
特にOSがベンダー提供のものであるときは、エラー情報もなかなか転がっていないので解決の糸口が見つけにくい。
有償サポートを結んでいれば、自力で解決出来なくてもサポート先が解決の手伝いをしてくれる。 でも、有償サポートを結んでいないと、独力で解決しないといけなくなり、開発者の負担が増してしまう。
有償サポート契約は開発者の身を守る保険のようなものなのだなと改めて考えさせられた一件だった。
Db2でスキーマ内の全テーブルの件数を確認する方法
Javaでboolean型の変数のtrue/false判定を行う方法について
これは何
Javaでboolean型の変数のtrue
/false
比較を行う方法についてつらつらと考えたもの
発端
若手メンバーが書いたコードをレビューしていたら
boolean flag = true; : if(Objects.equals(flag, false)) { : }
というコードを見かけた。
処理としては間違ってはいないのだけど、boolean型なので
if(!flag) {
:
}
と書くように指導した。
値を比較する時は、Objects.equals(a, b)
を使うようにコーディングルールを設けていたので
深く考えずにそのままコピペしてしまったのだと思われる。
boolean値の比較について
boolean値の比較方法については、下記2種類の書き方についての議論がよく見られる。
//否定を!マークで示す if(!flag) { : } //!マークは見づらいので == false と書いてわかりやすくする if(flag == false) { : }
他に書き方はないものかと思案してみた。
まず、Objects.equals
を使う書き方。Boolean.TRUE
またはBoolean.FALSE
と比較することで見やすくはなっているが、
比較対象を明示してあげないといけないというのが煩雑に感じる。
if(Objects.equals(b, Boolean.TRUE)) { : } if(Objects.equals(b, Boolean.FALSE)) { : }
apache commons
を見ていたところ、BooleanUtils.java
にisTrue()
、isFalse()
というメソッドがあるのを発見した。
BooleanUtils (Apache Commons Lang 3.10 API)
if(BooleanUtils.isTrue(b)) { : } if(BooleanUtils.isFalse(b)) { : }
こうやって書いてみると、意外とわかりやすい気もする。
引数の型がBoolean
なので、b
の値がnull
でも安心である。
そもそも、true
/false
のどちらなのかを判定したいのに、null
という第三の可能性が起きうる時点で
プログラムに何か間違いがある可能性の方が大きいわけではあるが…。
まぁ標準でBoolean
型とか、Objects
クラスにisTrue()
やisFalse()
メソッドが生えてくれるのが一番わかりやすいので
いつか実装されないかなぁ。
なぜJavaでgotoが予約語になっているのか
これは何
2020/7/22から開始される、観光のGOTOキャンペーンが開始されるニュースに乗っかって、プログラマ界隈でgoto構文の話題で盛り上がっていた。 その中で、なぜJavaではgoto構文が無いのに、予約語になっているのかという疑問を見かけたので確認した内容のメモ。
確認結果
Java言語仕様 の中に明記されている。 Java 14の言語仕様 (※リンク先はpdf)だと 43ページに記載がある。
The keywords const and goto are reserved, even though they are not currently used. This may allow a Java compiler to produce better error messages if these C++ keywords incorrectly appear in programs.
構文としては存在しないけど、予約語として定義しておくことで、誤ってc++
等のgoto
構文がある言語の感覚でgoto
と書いてしまったときに
コンパイラが検知できるように、ということ。
Java6の言語仕様も確認してみたけど、Java6の言語仕様とJava14の言語仕様で表現は全く同じになっている。
100日間目標体重との差をつぶやき続けた結果
これは何
100日間、Twitterで目標体重との差をつぶやき続けたことについての駄文
そもそもなんでやろうと思った
コロナの影響で息子の少年野球も活動休止になってしまい、週末に動かなくなったことで体重が急増してしまった。 これはいかんなぁと思いつつTwitterを眺めてたら尊敬する方が呟いていたので、便乗する形で初めてみた。
100日後に体が夏になる犬
— 犬エンジニア (@tada_suzu) March 24, 2020
1日目
目標まであと6.4kg
運動しなきゃ#natsukzk
体重は何で記録したか
Twitterに呟く+iPhoneのヘルスケアに記録した。 iPhoneのヘルスケアには体温も記録していたので、体温を入力する時に体重も入力した。
体重を減らすために何をしたのか
外で運動できない時期だったので食事の量を見直した。 毎朝体重計に乗っていると先日との体重差がわかり、前の日に食べ過ぎたことが分かるようになったのも大きかったと思う。
自分は仕事柄、リモートワークが出来なかったので平日はほぼ毎日、約1時間半の通勤をしていたこともあって、軽度の運動にもなっていたように思う。 もし、これがリモートワークだったら、全く体を動かしていないことになり、体重が増える一方だったと思われる。
Twitterを見ていたらフォローしている人がフィットネスをやってたので、自分も初めてみた。 これは効果があったのかどうかはわからないが、家での軽度な運動の習慣づけにはなったように思う。
私はプランクを終了したところです。手強くて、素晴らしいです!
— 犬エンジニア (@tada_suzu) April 24, 2020
フィットネスジャーナルを記録して、自宅で最高の結果を出しましょう。
アプリのダウンロードはこちら: https://t.co/oMbewbRa9x pic.twitter.com/QOLp5ilP6S
目標を達成できたのか
100日後に体が夏になる犬
— 犬エンジニア (@tada_suzu) July 1, 2020
100日目
目標まであと2.9kg
昨日よりわずかに減らして100日終了。
誰もみてない記録なので早朝にひっそり呟いて完結する。
お疲れ様でした。#natsukzk
100日終えて思うこと
32bit版Java11をダウンロード出来るJDK一覧
32bit版のWindowsでJava11の開発が出来るのか、みたいな呟きを見かけたので調べてみた。
@yamadamn さん作成の OpenJDKと各種JDKディストリビューションの情報源まとめ #minjava - Qiita で紹介されているところに絞っているので 実際にはもっとあるかもしれない。
ベンダー | 32ビット版の提供 |
---|---|
Oracle | × |
Red hat | × |
Azul Zulu | ○ |
SapMachine | × |
BellSoft Liberica JDK | ○ |
AdoptOpenJDK with HotSpot | ○ |
Amazon Corretto | × |
Azul Zulu、BellSoft Liberica JDK、AdoptOpenJDK with HotSpot の3つのみという結果だった。
まぁそもそも今どきWindowsの32bit版で開発するのは非常につらいので止めるべき。