作業ではなく意思決定に重点を置いたアプローチ

 (technicalwriting.dev)
3 ポイント 投稿者 GN⁺ 2024-10-20 | 1件のコメント | WhatsAppで共有

  • 意思決定に集中する

    • Every Page Is Page One からの引用が、技術文書作成へのアプローチに大きな変化をもたらした
    • 技術コミュニケーションでは主に作業支援について語られるが、多くの場合、人々が作業を完了するために必要な情報は機械の操作方法ではなく、意思決定を支援する情報である
    • 手順を文書化するだけでは十分ではない
    • ユーザーがどのような意思決定を下す必要があるのか、その結果は何かを知らせ、可能な限り意思決定を助けるリソースや参考資料へ導くべきである

GN⁺のまとめ

  • この記事は、技術文書作成における意思決定支援の重要性を強調している
  • 単なる手順説明を超えて、ユーザーがより良い意思決定を行えるよう支援することが必要である
  • 技術文書作成者にとっては、ユーザーに必要な文脈と情報を提供することが重要である
  • 類似の機能を持つ業界内プロジェクトとして Confluence と Notion が推奨されている

関連記事

1件のコメント

 
GN⁺ 2024-10-20
Hacker Newsの意見

  • ドイツの官僚主義について文章を書いているが、このアプローチには全面的に同意する
    私のガイドの大半は「これは何か、誰がやるべきか、なぜやるべきか」から始まる。人々が正しい理由で正しいことをしていると確認できなければ、とんでもない方向へはるか遠くまで進んでしまうことがある
    たいていの政府ウェブサイトはこうしたことを説明せず、自分たちが担当する手続きを完了するのに必要なことだけを求める。より大きな意思決定の一部としては見ず、ユーザーは自分が何をしているのかすでに分かっている前提になっている

    • 最後の段落に関連して言うと、UK govのウェブサイトはこの点をとてもうまくやっている。手続きを説明するランディングページがあり、警告や注意事項が表示されたあとで初めて実際のフォームに入力できる
      運転免許更新の Google 検索結果である https://www.gov.uk/renew-driving-licence から「Start Now」を押してみれば、意味が分かるはず
      「パワーユーザー」の立場だと時々邪魔に感じるが、全員を考慮しなければならないのは理解できる
    • このコメントを見るに、Every Page Is Page Oneが好きになりそう。要点は、人はドキュメントサイトのどのページからでも入ってくる可能性があるので、すべてのページが素早く文脈をつかませ、ユーザーが自分が正しい経路にいるかを簡単に判断できるようにすべきだということ
      本のタイトルもそこから来ている。サイトのどのページでも、ユーザーにとっては最初のページになり得る
    • こういうアプローチがもっと多くの技術文書にあればいいのにと思う。なぜそのやり方なのかをずっと気にしてしまうタイプなので、脇道にそれて進みが遅くなりがちだ

  • LLM の使い方ともよく合っている。私はいつも選択肢を求め、その中で何が最も筋が通っているかは自分で決める
    本質的には、意思決定の各瞬間における可能な選択肢を、不完全だが有用な形で吐き出してくれる、奇妙で魔法のような文書として使っている

    • レオナルドのような有名芸術家のもとで働いていた徒弟を思い浮かべればよい。師匠が輪郭とスケッチを描き、学生たちが監督の下で空白部分を埋める。時には師匠が学生たちのアイデアを盗むこともある
    • このやり方の例をひとつ挙げてもらえる？

  • すごくいい。短く、本質的で、洞察がある。私は大きな絵を見る思考に近いので、どうやるかだけでなく、なぜそうするのか、それがより大きな文脈とどうつながるのかも重要だ
    開発者には Jira のストーリーやタスクの Description フィールドを積極的に使って、なぜこれをやるのか、そして全体像とどうつながるのかの概要を書くよう勧めている。嫌がる人もいるようだが、かなり気に入る人もいる
    私はプロジェクトの全体像を示せるのでうれしいし、開発者はその全体像を理解することでより自律的に働けるので満足している

  • 文書が人々のよい意思決定を助けているかを測るのは、タスクをうまく完了できるよう助けているかを測るより、はるかに難しそうに見える
    タスクベース・手続き型の文書に最適化される理由は、会社が文書チームに価値の証明を求め、この種の文書には需要があり、短期間で測定して報告する方法も多いからだ
    しかし「この文書群は、誰かが正しいものを正しいやり方で作る助けになったのか」という問いは、組織ですら自社製品について答えるのが難しいレベルの話なので、文書の効果として抽象化すると非常にぼやけてしまう
    意思決定を助ける文書が書けないという意味ではなく、そうできたことを数字で証明するのがとても難しいという意味だ。複数の文書群が、意思決定を必要とするユーザーをどれだけうまく支援しているかを順位づけし、その根拠を説明することはできるが、それを会社が求める形で定量化する方法はよく分からない
    また、意思決定を支援するよう設計された文書群の構造が、タスクを支援する文書とどう違うのかも気になる。大きな分類は概念、参照、ガイドで同じだろうが、概念文書はずっと多くなり、概念を文脈づける余地も増える気がする。トピック間の依存関係やクロスリファレンスも増えると予想する

    • 最初の発想が「これを自分の書く文書の改善にどう使うか」ではなく、「これが自分の書く文書を改善するとどう証明するか」なのが興味深い。かなり厳しい環境で働いているように思える
    • 個人プロジェクトのように、ユーザーにとって最善だと思うことを自由にできる場であれば、意思決定支援を文書戦略の基盤にする可能性が高い
      誠実に働くという観点では、自分のプロジェクトで「意思決定支援」が最善だと感じるなら、業務文書にもこの戦略を持ち込む義務があるように思う
      幸い、近視眼的な管理者に締め付けられてはいないが、職場で説得しなければならないなら、こう進めると思う。まず戦略の論理を説明する。意思決定支援には筋が通っており、説得力もある。タスク文書も引き続き書くが、タスクは意思決定支援の部分集合にすぎない
      次に、サポートチケットやチャットルームでの議論などから、意思決定支援の不足が問題だった事例を長めに提示する。知的誠実さのため、文書関連のサポートチケット全体の一覧と、その中の意思決定支援関連の部分集合を一緒に示す。その比率が無視できない程度、たとえば 25% なら、「意思決定支援」をもっと深く見るべきだ
      最後に、利害関係者が自分の業務で経験した例を挙げられる。「CMS を何に置き換えるか決めるのが本当に難しかったのを覚えていますか？」といった具合だ

  • ふつう私がヒューリスティックなアプローチと呼ぶのはこれだ
    仕事にはファジー論理のようなアプローチが必要だと感じる。ただし、エンジニアにある程度の経験があるときに最もうまく機能する
    経験が不足しているなら、たとえ有能で頭が良くても、もっと指示的に進める必要がある

    • Thinking in Bets は、ソフトウェアエンジニアリングへの向き合い方として最も役に立った本のひとつだった。コードに関する本ではなく、限られた情報環境で効果的に意思決定する方法についての本だ
    • 仕事にファジー論理的なやり方で取り組む、というのがどういう意味なのかよく分からない。もう少し噛み砕いて説明してもらえる？

  • チームの文脈で意思決定を行うよいアプローチについては、Rich Hickey がここで説明している: https://www.youtube.com/watch?v=c5QF2HjHLSE
    講演タイトルは「Design in Practice」だが、実際には意思決定についての内容だ

  • 「仕事とは、ある意思決定から次の意思決定へ進むためにやるべきすべてのことにすぎない。」 — Venkatesh Rao, Tempo

  • 以前から似たようなことを主張してきた。ツールを高いレベルで説明するだけでなく、特に人はしばしばマーケティングモードに入ってしまうので、そのツールがどんな問題を解決するために設計されたのか、そしてその過程でどんなトレードオフをしたのかを語るべきだ。
    そうすれば、ツールと利用可能な選択肢・モードなどを文脈の中に置きやすくなり、自分に合っているかをすばやく判断できる

  • この助言は少し混乱する。誰の決定なのか。ツールの作り手の決定なのか、ユーザーの決定なのか。
    一般的には過度な単純化のように見える。まず、自分が使っている文書が学習用、目標志向型、理解用、情報提供用のどの種類なのかを理解するほうが有用だ [1]
    たとえば、ある関数のAPIを調べているときに「決定」の情報が大量に出てきたら、いら立つかもしれない
    1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

    • 文書は常にユーザーの要求を扱わなければならない。そこはなくならない。言及されている文書の4象限であるDiataxisも同じだ。
      この記事が共感を得る理由は、よく知られた2つの戦略の死角をあらわにしているからだと思う。誰もがユーザー中心の文書を作ろうとしており、多くのチームがDiataxisに従っているが、それでもなお文書だけで仕事を終えることに苦労している。
      「文書は決定を支援すべきだ」という基本的な観点から出発すれば、文書をより有用にする道になりうる

  • 人々が自分のシステムをどう使って決定を下すのかを知るのは重要だ。そうした知識は、システムを保守したり拡張したり新しく作ったりするうえで不可欠だと思う。
    しかしこの記事は、より高い責任を提案している。ユーザーの意思決定プロセスを文書化し、文脈と選択肢、決定の結果を伝えるべきだということだ。
    そういう責任を持つ「意思決定支援システム」で働いたことがあるが、ものすごく速く複雑化した。人は、結果が100%確実に分かっていても、その結果をめぐって議論するのが好きだ。不確実性を含む自動メールも嫌うし、現実にははるかに多くの選択肢があるのに、文書が二者択一の選択を求めることも嫌う。
    この記事を超えて、本では統制の概念も扱ってほしい。ある動作を文書化するには、その動作に対する保証や強制がある程度なければ、文書は権威を保てない。個人的には、権威と統制の欠如が、https://www.plainlanguage.gov のようなライティング・イニシアチブにおける、よくある大きな死角だと思う

    • r/technicalwritingでこの記事について書いた内容をもう一度引用すると、Bakerのアイデアで本当に重要なのは、技術文書教育の教義がタスク中心に絶対的に合わせられているという点だ。
      プロのテクニカルライターを調査すれば、多くが「ユーザーがタスクを達成できるよう助けること」を文書の主要目標、ひょっとするとTHE主要目標だと信じているはずだ。
      Bakerの短い引用は、ラテン語の意味で「根に戻る」という点でかなり急進的だ。私たちの根本的な前提の1つが大きく不足していると示唆しているからだ。
      個人的にBakerのアイデアが興味深いのは、現在テクニカルライティングに期待されている基準よりもはるかに高い基準を置いているからだ。多くの文書は、タスクが文書化された時点で「任務完了」と見なしているが、Bakerはそれだけでは不十分だと言っているように見える。
      タスクはもちろん引き続き文書化すべきだが、タスクは決定を構成する情報の下位集合だ。
      Bakerの本が、ここで言われているような統制を論じていたかは覚えていない。私には新しいアイデアなので感謝している。
      思い浮かぶ具体的な統制の例はこうだ。私の文書のかなりの部分は他のオープンソースプロジェクトのページに依存しているが、その外部ページの品質が低いなら、その文書を改善することも自分の責任である可能性が高い。多くの人は自分のサイト外の文書は自分の責任外だと見るかもしれないが、本当に決定を支援するつもりなら、誰がその文書をホスティングしているかは重要ではない。
      良いオープンソース市民として振る舞う姿勢から学べることは多いのかもしれない