garbagetown

個人の日記です

JJUG CCC 2017 Fall に登壇しました #jjug_ccc #ccc_a1

JJUG CCC でお話ししてきました!

www.java-users.jp

2017 Spring に続いて二回目。前回よりはリラックスできたかなー。

発表資料はこちら。

p キーを押すとスピーカーノートが表示されます。当日はピンマイクでうろうろしながらスピーカーノートを見ずにお話ししたので、お伝えし忘れたことがぽろぽろありました。反省。

資料中で紹介している gradle プロジェクトも以下にアップロードしました。

github.com

登壇の経緯

業務ドキュメントの作成について、以下のような課題を感じていました。

  • バイナリフォーマットとバージョン管理ツールの相性が悪い
  • いつ、なにを、どのように書けばよいのか、いまいちよく分からない
  • レビューがうまく機能していない気がする

いつ、なにを書くべきなのかについては、システムエンジニア Advent Calendar 2016 に書きました。

この頃は Markdown でドキュメントを書けないかと考えていたのですが、その後に参画した案件で採用した AsciiDoc と PlantUML に手応えを感じたので、この成果を共有したいと考え、関係各位の了承を得た上で CfP に応募しました。

KPT

以下、振り返り。

Ask the Speaker

以下、登壇後に頂いたご質問など。

日本語でセクションタイトルを書いても自動生成される id は問題ないか

実際の案件でも日本語でセクションタイトルを書きましたが、特にハマったことはないです。自動生成 id でハマったのは以下の二件。

  • 予期しない記号がアンダースコアに置き換えられた
  • セクションタイトルが重複して連番が付与された

いずれもビルド後の HTML ソースから自動生成された id を確認して解決しました。事前にカスタム id の付与ルールを検討するのもよいと思います。

Table セルを改行して記述した場合、列数はどのように判定されるのか

|A |B |C |D と書けば 1 行 4 列であることは明白ですが、B や C の後に改行すると列数が分からなくなるのでは?という鋭いご質問ですね。

[cols="xx,yy,zz"] のように明示しない場合、一行目の列数で判定されるようです。

実際の案件では以下のルールで記述しました。

  • [cols="xx,yy,zz", options="header"] の指定必須
  • 列ごとに改行
  • 行ごとに空行を挿入

GitLab CI を使えば Jenkins は不要では?

GitLab CI が登場するより前から利用している docker-compose を再利用したため、GitLab と Jenkins を組み合わせて利用しています。

新規に構築する場合は GitLab CI でもよいと思います。

まとめ

今回も登壇駆動勉強が捗りました...

また、資料を書き進めていくにつれて「あのときこういう言い方をしたからみんな受け入れてくれたんだなー」という気付きを得られたのが個人的に大きな収穫でした。

拝聴した各セッションや全体の感想は別途投稿します。

朝一番のセッションにも関わらずお越しいただいた方々、スタッフの方々、某案件でお世話になった方々、お忙しい中レビューしてくださったくらもとパイセン、本当にありがとうございました!