【書評】ドキュメント作成システム構築ガイド

ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]

読むに至った背景

現場や会社でのドキュメントをMicrosoft Office使っているが、更新が頻繁に入ると凄い手間。
チームでドキュメント作成・更新すると必ずコンフリクト*1が起きて、直すのに時間がかかる＆マージ漏れ発生の可能性大。
そんな作業に嫌気が刺していたので、システムチックにドキュメント整備したいと思って読んだ。

Microsoft Office製品はあまり好きじゃない。
いや、あえていおう！力スであると！
奮起せよ！システムエンジニアたちよ！エクセルドキュメントからは脱せねばならない時にあるのだ！

まぁ、GW暇だったからってのもあります。(＞＜)

内容

()内は、思った感想。

モダンなドキュメント作成

ドキュメント = 読者に記述内容を早く正確に伝えるのが目的

ドキュメントの品質

人が読むしかない。
= 作成・維持は人手になるので、コストが大きく、品質口上が難しい。

ドキュメント作成の注意点

対象読者の想定

初学者：話しの中核よりも導入を大切にする必要がある。
エキスパート：説明を省いて話しの中核を詳しく書ける。

可読性

ドキュメントは、読みやすくあるべき。読みにくいドキュメントに意味はない。

問題になる要素

• 一文が長い(= 伝えたい事がブレやすい)
• 二重否定(人の頭では解釈しにくい。中二病が一般人に理解されないのと一緒！)
• 専門用語の不一致

正確性

• ドキュメントと仕様の不一致
• 曖昧な記述

課題管理と連動して、メンテしていけば無くせるかも。

利用する表現

感情表現は排除。感情は敵意を伝播させやすい。
(ネットで書くと敵意が強めに出るのは、テキストベースだからな気がする。)

スタイル(見栄え)

スタイルが悪い = 可読性の悪化
一貫性がなく、稚拙な文章になる。
(外面重要。外面が悪いと興味すら持ってもらえない！人間と一緒！)

規約に基づいたドキュメント作成

ドキュメント作成の注意点　→　規約にまとめるしかない。
複数人で作成する際は、規約の存在が重要になる。
(ベストはないことだけど、人である以上無理だね)

共同作業の効率化と問題点

• 変更箇所の衝突
• ドキュメントの理解不足
• 言葉使いの不一致

(関係ないけど、クローン人間でも言葉使いの不一致は起こるのだろうか？)

継続的インテグレーション(CI)

ドキュメント = 編集され続ける = CIが有効である

ドキュメントでやるべきCI

• ドキュメント生成
• ドキュメント検査

どうやって実現するか？

Markdown

• メリット
  • シンプルな記述ができる
  • テキストベース(マージが楽！)
  • GitHubなどで広く普及
• デメリット
  • ファイル分割ができない(ファイルが超大になり、分割作業できない)
  • (独自拡張が多い)

(メモ程度ならMarkdownは有効。実際、自分もよく使う。)

GitHubによるドキュメント管理

従来のフォルダやファイル名に日付をつけることの問題点

• 編集内容が理解できない。
• 並列開発できない。
• (どれが最新か分からない。ファイル名とタイムスタンプに矛盾があるときは、怒りが炸裂する！)

VSSでやることのメリット

• コミットメッセージから変更内容の検討がつく
• 編集履歴の共有
• 競合しても解決が楽

(メリットしかないはずなのだが、現場がそうなってないのは何でだろう～何でだろう？)

RedPenによるドキュメントの自動チェック

RedPenの特徴

• 設定でチェック内容を変えられる
• マークアップ言語対応
• (日本語・英語とかの意味の)言語に依存しない

本格的なドキュメント作成

AsciiDoc

マークアップ言語。ドキュメントを複数ファイルに分割・統合する機能を持つ。
複数の開発者がいても、生産性を落とさない。
(たしか、次期Springがこれを使った機能提供するハズ)
(過去記事に書いてあったので、興味ある方はそちらを参照)

suzaku-tec.hatenadiary.jp

Markdownの存在から、なかなか普及率が伸びていない。
(あと、Python製のSphinxの存在もある。競合相手がなかなか強者なのだからなのだろうか？シェア争いが均衡気味？？)

ドキュメント作成システムの構築

• GitHub：バージョン管理
• Jenkins：CIツール
• RedPen：自動検査ツール
• AsciiDoctor：出力ドキュメントのフォーマット変換

感想

大体既知の内容だった。
ただ、AsciiDocは、知ってはいたけど、詳しくは知らなかった。
今後、需要がありそうなので、早めにキャッチアップしておきたい。
というか、Excel仕様書を脱したい！！！

RedPenは、どこかのライトニングトークで紹介しているのを聞いた気がする。
Atomエディターのパッケージも提供されているので、使ってみるといいかも。
実際使っているが、デフォルト設定で指摘されたことがない。本当に機能しているか若干不安な今日このごろ。
僕がとてつもなく優秀ってことにしておきたい！

実際、ドキュメントをコードと同じように扱いましょう的な内容だった。
これには、激しく同意。
あと、なんども言うけど、Microsoftの仕様書は絶対廃止！
コンフリクト起こすと、立場の弱い俺がいっつもマージするのが、苦痛で苦痛でしょうがない。
Excelでいいやって思っている奴は、一回マージ作業してみろ！
絶対二度とやりたくないと思うから！
※経理帳票とか変更がほぼないのは、Excelの方がいいので、TPOを考えず削除すると異端になるので注意！

ドキュメントはコードと同じ扱いって考えは前からあって、VSSで管理すべきってことは前から考えていた。
文章の検査も自動化する発想がなかったので、それを得られたのが収穫。
文章の検査は、これから伸びる分野だと思います。
検査がある程度自動化されるようになれば、人はより概念にフォーカスを当てて、意思疎通の効率化と正確さが重要になる。
自動化できないところを如何に効率化よくしていくかが、ますます重要になってくると感じた。

*1:競合