🗂

なぜ組織にDocumentが必要なのか👊

2024/05/10に公開

概要

Documentを書く文化を持つことは、暗黙知を形式知に、フロー情報をストック情報に変える基礎となります。これによりナレッジの蓄積が行われ、過去の情報のアーカイブが閲覧可能となり、あらゆる情報にアクセスできる透明性と効率をもたらします。

テ キ ス ト の こ こ が す ご い

  • メソポタミア文明とかからある
  • 紀元前の中国で紙が発明されてからますます使われる
  • 15世紀に活版印刷が発明されてからは書物が簡単に生産可能に
  • 印刷の組版を指示するためのマークアップという考えかたが生まれる

組織にDocumentがなぜ必要か

組織が継続した改善を続けるためには、文書化の戦略を定めておくことが必要です。

例えば少ない人数の組織では会議やSlackなどで情報を理解してもらうことが可能でしょう。しかし組織がスケールするとともに個人の暗黙知の割合が増えていけば、共通の認識を持つことが難しくなっていきます。断片的な情報だらけの組織では、何度も同じ情報を要求したり、確認のための会議が発生したりと非効率な場となってしまいます。

組織が文書化戦略を持つことは、これらの問題を未然に防ぎ効率的な運用を行うための取り組みです。

文書化戦略で得られるメリット

  • 暗黙知が形式知になる
  • アーカイブ・蓄積が可能
  • 検索可能になる
  • 引用可能になる
  • レビュー可能になる
  • 新規参入者にとってDocumentはキャッチアップのための資源
  • 組織のスケールと共に非同期コミュニケーションの重要性が高まる
  • DevOpsの一部である
  • 優れた文書を書けるようになる
  • リモートとオフィスのハイブリッドワークで成果を出す文化を作る
  • プロダクトと組織がスケール可能な文化を作る

ベストプラクティス

テクニカルライティングに従う

テクニカルライティングは、明確な技術文書を書くための技術です。特に重要な項目を紹介します。

  • 構造化する
  • 用語を一貫して使用する
  • 対象の読者を特定する
  • 箇条書きリストと番号付きリストの違いを理解して使用する
  • 前提知識を明らかにする

Technical Writing One introduction

信頼できる唯一の情報源 (SSOT)を実現する

情報を集約する場所を決めてSSOTを実現しましょう。SSOTがある状態なら次のようなメリットが得られます。

  • 関連するDocumentへのリンクを記載する
  • チャットツールで会話するとき、引用する資料へのリンクも記載する
  • 曖昧な単語を定義し、共通の認識を作る

真の SSoT とは、チームすべてのナレッジを 1 か所に集めたものです。ここでは、質問が回答に変わってドキュメントが常に最新に保たれます。

Wikipedia 信頼できる唯一の情報源

Atlassian チームのために信頼できる唯一の情報源を構築する

マークアップ

プレーンテキストを用いたマークアップの方法として、やはりMarkdownを使用することがおすすめです。Markdownは多くのエンジニアが技術文書の作成と編集に使用する軽量のマークアップ言語です。読みやすく書きやすいプレーンテキスト形式を使用して記述します。

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Daring Fireball: Markdown

企業カルチャー事例

GitLab

初期段階のスタートアップでは、文書化戦略を避けがちです。チームメンバーが数人しかいない場合は、会議、Slack、または電子メールのスレッドを通じて全員に情報を提供し続けることが可能です。

しかしチームが拡大するにつれて、文書化の必要性とそれを行わないことによるコストが同時に増加します。企業が年齢を重ね成熟するにつれて、文書化戦略の導入はより困難になり、さらに重要になります。

構造化された文書を優先する組織は、信頼できる唯一の情報源の恩恵を受け、効率的に運営できます。構造化された文書化に力を入れていない組織では、チームメンバーが同じデータの断片を永続的に尋ねたり、尋ね直したりするのを見るしかなく、最適とは言えない知識伝達のループが生まれます。

https://about.gitlab.com/company/culture/all-remote/handbook-first-documentation/

HashiCorp

書くことは、優れたアイデアがどこから来たかに関係なく、確実に共有され、適切に評価されるようにするための平等化の力として機能します。文章の変更を提案するプロセスは、あなたが若手社員であっても会社の創業者であっても同じであり、口コミに頼るのではなく、同僚に直接提案することができます。

hashicorp writing-practices-and-culture

参考

書籍

企業事例

ライティング技術

GitHubで編集を提案

Discussion