GitLabに学ぶパフォーマンスを最大化させるドキュメンテーション技術〜第2部〜
Daily Blogging17日目
「GitLabに学ぶパフォーマンスを最大化させるドキュメンテーション技術」を最後までとりあえずざっくり読んだのでざっくり思い出しながらアウトプットしていくぅ
第2部は実際のドキュメントの作り方を詳しく解説してる
主に
- ドキュメントの注意点
- テクニカルライティング
- 思想に基づいたドキュメントづくり
- ハンドブックのテンプレート
あとは文書の書き方とかスタイルについても
めちゃくちゃ細かく解説してる。
今はそこまで細かいのはいらないので結構はしょってよんだ
ドキュメントの注意点
大切なのは2つ
- 目的
- 対象範囲
目的
何事も目的が大切
目的はいいこといっぱい
- ドキュメントの方向性が明確になる
- 何を書くべきかが明確になる
- ドキュメントが正常に機能しているかの指標になる
目的があることによって、どういう内容をどれくらい書けば良いのかが明確になるし、そのドキュメントがちゃんと機能しているかは、その目的を達成できているかで判断できる。
ドキュメントってとりあえず情報残しとこっていう感じで書くこと多いから、あらためて目的を意識するのは確かに大切そう
対象範囲
誰が読む想定なのかっていうのも大事
人によっては前提知識があって余計なことは書かなくても良いし、全然知識ない人だったら言葉は慎重に選ぶ必要がある。
前提知識も他のドキュメントで確認できるようにしてあるべきであり、どの順番で何を読んでいけば良いのかもドキュメントにリンクを貼り付けてわかりやすくした方が良い。
テクニカルライティング
テクニカルライティングとは
技術的な内容を目的や読み手に合わせてわかりやすく伝える手法です。技術ブログやドキュメントなどの文章でアウトプットする際に、より伝わりやすい文章を書くために活用されます。
by google
GitLabでは、全社員にgoogleのテクニカルライティングコースを受講してもらってるらしい
これでテクニカルライティングの基礎を学ぶ。
GitLab独自の講座も用意しているみたいで、GitLabならではのルールはそれで学んでもらってる。
ライティングに関するコースをわざわざ受講させるのって珍しい
ドキュメントカルチャーを作る覚悟がすごいねっ
思想に基づいたドキュメントづくり
GitLabにはいくつか思想がある。
その思想をドキュメントを書くときの思想にもしている。
色々あるけど一つだけピックアップ
イテレーション
ドキュメントは「下書き」である
ドキュメントは書いて終わりじゃないっ
常に改善、更新され続けるものだよ
ドキュメントを管理する上でこのマインドはマジで大切だと思う
基本的にドキュメントって書いて終わりだし、ドキュメントに間違いあってもなかなか直さなかったりして形骸化してく。
その様子を何度も見てきた。
ハンドブックのテンプレート
The GitLab Handbookみたいなやつをパパッと作れるテンプレートを紹介してくれてる。
嬉しいっ
これがあればGitLabのドキュメント管理はすぐに真似できる
感想
ドキュメントも奥が深いなぁ。
ドキュメントカルチャー作るのもやっぱり相当な覚悟と徹底したマインドセットが重要なんだなぁと感じた。
すぐに全部真似はできないけど、イテレーションのマインドとかちいちゃいところから実践したい
Discussion