KDOC 199: 文書づくりの仕事で事前に決めておくこと

• 作成
  • 2024-07-20 貴島
• レビュー
  • 2024-07-22 貴島

• 範囲が明確でない仕事
• 常識が全く異なる会社間の仕事
• 誰でも簡単に理解できる仕事

は、トラブルになりやすい。

提出した開発ドキュメント/マニュアルに対する、無限の些細な修正依頼、作業範囲の拡大…を体験したことがある¹。最初に決めていたのだがその内容が甘かった。あとから合意を盾にできなかった。依頼する/される側両方が不本意な結果となる。

文書作成の仕事はソフトウェアよりさらに、形のないものである。何をもってゴールとするかは人によって大きく異なる。そして専門知識なく理解できるものなので、些細なことに対して誰でも無限に議論・指摘できる。本質的な議論を全くせず、時間だけをかけさせるのは難しくない。費用対効果を悪化させていく。

避けるためには、事前の相互理解と合意が必要である。顧客の目的や価値観を明確にし、プロセスについて合意して取り掛かることでスムーズになされる可能性が高い。

前提を表明/合意する。

• 文書作成プロセスが誰にとっても 生産的な プロセスでなければならない。作成前にライフサイクル全体を最大限考慮し、これに寄与しない事項はできるだけ排除しなければならない
  • 作成者: 作成しやすい
  • レビュワー: レビューしやすい
  • 更新者: 更新しやすい
  • 読者: 読みやすい
• 文書に対するポリシーは、会社/個人/ユースケースによって違いがある。違いを認識することは少なく、トラブルの原因になりやすい。未然に防ぐために高い頻度で連携し、相互理解に努める努力が必要である

文書の位置づけを合意する。この大まかな合意を根拠に、後の議論を進める。

• 品質
• コスト
• 納期

↑の優先順位を決定する。

• 何を目的にした文書なのか
  • ユースケースを列挙する
  • すべてのユースケースの具体例を列挙する
• 誰を目的にした文書なのか
• 前提にできる知識
  • 特定の業務知識
  • 特定技術の知識
• 公開範囲
• 提供する機能と優先順位を示す
  • 例
  • システムの概要や構造を把握したい
  • コードの詳細を理解し、追加修正を簡単にしたい
  • ソフトウェアの品質を保証したい
  • プロジェクトを円滑に進めたい
  • ソフトウェアを適切に使用させたい
• コストの優先順位を合意する
  • 例: 機能性 > メンテナンスコスト > フォーマット
• スナップショット文書と常時最新文書をどうするか
  • ソフトウェアやプロダクトを取り巻く状況は変わりうる。常に最新とする文書は非常にコストがかかり、多くの場合そこまでは必要ないことが多い。常に最新とはしないスナップショット型文書と常時最新文書を分けて管理するとよい
  • 常時最新文書において、最新さをどう担保するか。複数人が編集するなかでどう読みやすくするか
• 意味がわかればいい種類の文章なのか、オフィシャルなニュアンスとフォーマットが必要な文章か
• やらないこと
  • すべてのケースに対応すること

文書で「よい」とする方向性を合意しておく。細かいフォーマット > コスト という組織も中にはある。

• 冗長 –— 簡潔
• ローコンテキスト –— ハイコンテキスト
• ラフ –— フォーマル
• 永続 –— スナップショット
• 丁寧 –— 命令
• どちらが正か明らかな根拠を持てない点については、宗教論争になるのでなるべく議論しない
  • 統一する必要がある項目は、事前に明文化しておく必要がある
  • 文書の体裁にどこまで厳格か(コストをかけるか)
  • 事前に取り決めのないフォーマット事項は、レビュワーが自身で修正する
• ソフトウェアが対応しない体裁には対応しない

生産性に疑問があるが、指定がないかを事前に確認する。

• 表記ゆれのポリシー
• 段落の使い方。階層を多用するか、フラットにするか
• 番号無し/付きリストの使い分け²
• キャプション番号
• 目次
• 脚注のポリシー

レビュー時の観点について例を上げる。

• 想定する読者が理解できるか
• 手順が再現可能か
• 誤字脱字・フォーマットミスがないか

• どのソフトウェアでやるか
  • 誰でも編集しやすいか
• どうレビューするか

工程と担当者(社)の明示。最初から上長など関係者全員に関わってもらう。

• 事前すり合わせ – A, B, C
• 章立て作成 – A
• 章立てレビュー – B, C
  • 修正作業 – A
• 本文作成 – A
• 本文レビュー – B
  • 修正作業 – A
• フォーマットレビュー – B
  • 修正作業 – B

文書それぞれのライフサイクルの例を示す。

• ステータス³
  1. ドラフト DRAFT
     • 作成者が草稿を作成している状態を示す
  2. レビュー REVIEW
     • レビュー者がレビューしており、必要に応じて作成者が修正する状態を示す
  3. 承認 APPROVE
     • レビューが完了し、読者が文書を利用できる状態を示す
  4. 廃止 DEPRECATE
     • 文書の内容が古くなり、読者に参照を推奨しない状態を示す。

• なぜソフトウェア開発のドキュメント管理は難しいのか - DMM inside

• パーキンソンの凡俗法則 - Wikipedia

  組織は些細な物事に対して、不釣り合いなほど重点を置く

• KDOC 17: 社外の人と開発するコツ。異なる常識を持つ人と働く方法が共通しているため
• KDOC 101: 先にインターフェースを文書化するとやりやすい。文書関係が共通しているため