読者です 読者をやめる 読者になる 読者になる

エンターテイメント!!

遊戯王好きのJavaエンジニアのブログ。バーニングソウルを会得する特訓中。

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

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

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

読むに至った背景

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

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

f:id:suzaku0914:20160515220912j:plain

まぁ、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:競合