ドキュメントもソフトウェアなので、ソフトウェアの開発手法がそのまま適用できます。
つまり
・要求定義
・ユースケースの分析、つまり、誰がなんのために見るかを想定
・利用者のワークフローを分析
・説明する対象の構造を分析
・優先度やワークフローにしたがって構造を設計
・設計にしたがって実装
・テスト
という流れ。
成果物をJavaのコードで書くか日本語で書くかの違いでしかありません。
わかりにくいドキュメントというのは、説明する対象をその構造だけにしたがって書いている傾向があると思います。
それは、システムで例えればデータベースをそのまま見せて、あとはSQLで勝手に操作してねというもの。
たしかにデータは全て整っているけど、何も知らない人が使えるものではないシステム。
つまり、仕様の羅列になっていて、ユーザーインタフェースが噛んでいないドキュメント。
