執筆ガイドライン【CCG執筆者向け】
本ブログは ナレッジサイトである Classmethod Cloud Guidebook(CCG) 1 の執筆者向けに公開しているブログです。 一般的な執筆活動の運営でも参考になる部分があると思うので、ブログにて公開しています。
CCGの執筆ガイドラインを共有します。 執筆の際の意識付けやリファレンスとして活用してください。
はじめにまとめ
本ページの要旨は以下のとおりです。
- 何を書くか
- 「AWSの活用や統制に役立つナレッジ」を体系化して、メンバーズに最適化した形で提供します
- 執筆の進め方
- ✏️執筆活動: 執筆ブランチを作成して執筆します
- 🔍レビュー: レビュアーと会話して文章をより良くします
- 📘CCG反映: プルリクエストをマージして開発サイトに反映します
- 執筆の意識
- 「CCGの思想」を意識します
- 既存ドキュメントをリスペクトします
- 指摘は批判・攻撃ではありません
- スモールスタートを意識します
- 執筆の技術
- (大前提として) Better than Nothing
- テクニカルライティングは役に立ちます
何を書くか
ターゲットは「クラスメソッドメンバーズ(以降メンバーズ)のお客様」となります。
「AWSの活用や統制に役立つナレッジ」を体系化して、メンバーズに最適化した形で 提供します。 そのためにドキュメントを執筆します。
– 画像: クラスメソッドメンバーズのお客様向けに公開している「Classmethod Cloud Guidebook (CCG)」の使い方 | DevelopersIO
コンテンツは GitHubのプライベートリポジトリで管理されていて、 各ページは Markdown 形式で記載されています。
執筆の進め方
前提: ブランチ運用
Git/GitHubのブランチ運用の概要図を以下に示します。
執筆者が関係するブランチは developブランチ、および 執筆ブランチです。 developブランチから執筆ブランチを作成して、執筆活動を行います。
執筆ブランチの変更内容を developブランチへ取り込んだところで、 「執筆活動の1サイクル」が終了します。
執筆の全体フロー
執筆活動の全体像は以下のとおりです。
大きく分類して、「執筆活動」「レビュー」「CCG反映」の3ステップです。 各ステップの詳細を説明していきます。
✏️執筆活動
執筆ブランチを作成する
developブランチをソースにした、新しいブランチ(執筆ブランチ)を作成してください。 ブランチ名にルールは無いです。
🔧Tips: 軽微な追記・更新の場合は developブランチの該当ファイルから [Edit this file] を選択すると楽です。 そのまま編集でき、プルリクエストまで送れます。
ドキュメントを書く
メインの執筆活動です。 ブラウザ(GitHub)上、もしくはローカルのお好きなエディタで執筆していきましょう。
ドキュメントの文法については以下ブログを参照ください。
また、コンテンツごとに独自の書式やパターンがあります。 これは各コンテンツの管理ページ(もしくは活動チャンネル) で把握してください。
🔍レビュー
プルリクエストを作成する
作成・更新したドキュメントを反映させるには プルリクエストを使います。 base(=変更を適用する場所)を developブランチとして 、 プルリクエストを作成してください。
🔧Tips: まだ未完成で執筆中の内容を共有したい場合、ドラフト(Draft) プルリクエストが役に立ちます。
指摘項目を修正する
レビュアーからの指摘があった場合は、対応します。 執筆ブランチ上で追加のコミット(修正)を行ってください。
🔧Tips: 指摘を貰ったかどうかは、 is:open is:pr author:@me review:changes-requested フィルターを適用して確認できます。
再度レビューを依頼する
修正が完了したら、指摘を貰ったレビュアーに 「再度レビューをお願い」してください。
具体的にはレビュアーに対して Re-request review を適用します。
📘CCG反映
プルリクエストをマージする
「レビュアーから一定数の承認(Approve)が得られた状態」かつ 「校正などの自動チェックに合格している」場合に、 マージ可能になります。
[Merge pull request] を選択して、マージしましょう。 執筆者とレビュアー、どちらかが実施します。 デフォルト設定/パラメータでマージしてOKです。
マージされるとCCG開発サイトへ、変更が自動適用されます。
執筆の意識
「CCGの思想」を意識する
社内でまとめている「CCGの思想」を意識して、執筆を進めます。 以下「CCGの思想」の抜粋です。
- クラウドジャーニーを歩むためのガイドブックであること
- メンバーズに最適な形でナレッジを体系化していること
- DevelopersIO へのブログ執筆がメインであること
- クラスメソッドのカルチャー に繋がること
既にあるドキュメントへのリスペクト
どんな内容であれ、 既にあるドキュメントをリスペクトします。
「ここが "悪い" ので、アップデートする」よりも 「こうしたら "より良くなる" ので、アップデートする」 意識が良いでしょう。
レビューの指摘は批判・攻撃ではない
指摘は批判的/攻撃的に見えるときがあるかもしれません。
執筆者とレビュアーには「CCGをより良くする」共通の目的があります。 協力関係であることを忘れないようにします。
スモールスタートを意識する
小さな規模で素早く展開することを意識します。 その後も、小さい粒度で多数の改善を 積み重ねていくのが良いでしょう。
関連して、プルリクエストの単位はなるべく細かくしましょう。
執筆の技術
(大前提) Better than Nothing
そもそも技術を考える前に、 「無いよりはマシ」 を実践したいです。
後述するテクニカルライティングなど 「執筆のクオリティを上げる術」はたくさんありますが、 それらにこだわり作り込みすぎるのは良くないです。
最低限伝えたい内容が書ければ、とりあえずプルリクエストを出す。 その後に改善していくような流れが理想です。
執筆の技術を持っていると、より役には立ちます。 しかし執筆のハードルにはなりません。
テクニカルライティング
テクニカルライティングは技術的な内容を 分かりやすく伝えるための手法です。
CCGにおいては、 「AWSサービスの技術的なトピック」や 「セキュリティや統制に関する考え方」が コンテンツとしてあります。 それらコンテンツを分かりやすく伝えるために、 テクニカルライティングは役に立ちます。
参考になるものは書籍やインターネットにたくさんあります。 以下に私が見て(読んで)、良かったものを紹介します。
(参考) 個人的に意識している点
テクニカルライティングとして、何を意識するかは人それぞれです。 参考までに、私が特に意識している点を以下に記載します。
- 読み手を意識する
- 文書の目的を意識する
- 文書の要点をはじめに書く
- 文書を完成させるプロセスを確立する
- 目的を書く (誰向け？何を達成する？)
- アウトライン(見出し)を書く
- 各見出しの段落ごとに、伝えたいことを1文で書く
- 順番に段落の文章を埋めていく
- 画像や表を挿入していく
- 1文を短くする
おわりに
以上、CCGの執筆ガイドラインでした。
ガンガン執筆していきましょう！
参考
- CCG
- 執筆の意識
- クラスメソッドのカルチャー | classmethod
- CCGの思想 - (社内ページを参照)
- 執筆の技術
- GitHub操作周り
