実際にちゃんと日程決めて 1 日なるべくドキュメンテーションする日にしようという事にしてやりました。ターゲットは主に社内の各種サービス。内部 API とかライブラリとか、そういう類の。

「ドキュメント改善しないとまずいよねー」「はー」「なんか一日集中してやる日とかつくればいいんじゃ」「そこまでするかねえ」「いやーそうしないと人間絶対やらないからチーム全体で今日はそれをやるぞ!って決めて動かないとやらんでしょ」みたいな流れがあってな
— そらは (@sora_h) April 14, 2015

「今日はみんなこれをやる」と決めると、やるかー、っていう気分になるじゃん。いろいろやらなきゃいけないタスクはあるけど、それは置いておいて みんなで やるという空気にするとわたしはやるかーってなる。一人でやるぞーってなるより、やるかー! ってなるんだよな。

どこをとりあえず見ればいいか分かりにくい、ドキュメントのある場所がまちまち、そもそもドキュメントがない! という状態を改善していく。具体的には

置き場所がバラバラ
- 基本的に、概要や運用寄りの情報は社内 Wiki に統一。みんなだいたい、まずここを検索するような習慣があるから
- Pull Request して実装の変更とともにレビューできたほうがよい、API リファレンスとかは Git リポジトリに突っ込んで管理。GitHub Enterprise の web view を通して読む (Markdown)
どこを見ればいいのか分かりにくい
- Wiki ページ先頭を見て概要と、Getting Started / Tutorial 的ページへのリンクを置いておく
  - Getting Started ページにもだらだらと書かない、細かい tips はリンクなどに留めて別のところに置いていてスッキリさせる
- 加えてページを分割する、1 ページにだらだらと書かない
- Tutorial も体裁を整えて見やすく
そもそもドキュメントがない
- 概要しかない…
- outdated がすぎる…
- というわけで書く。

…とはいうもののまだ完璧になっている訳じゃないのでこれからも精進が必要だしわたしも自分の管轄するところで書かれていないドキュメントを書かなきゃならない…。

しかし社内ブログに載せられたやつも自分の口頭での発言がテキストに起こされていた…ってやつなんだけど、これはさすがに美化されすぎなきがする。こんな綺麗な口調で言った覚えはない…ないぞ…

あとはドキュメントを書く習慣を付ける、第三者から見てわかりやすいドキュメントを書くみたいなのはいまだに下手だなぁと思ってるので、なんか良い文献や方法などあったらおしえてくださいませ。

diary.sorah.jp

15 Apr 2015
ドキュメントの件