チーム内ドキュメント運用で問題があると思うところ

元記事は内部向けドキュメント運用で問題があると思うところにある。

• 情報が埋もれて、調べづらい
  • 具体的に困った事例
    • mackerel3-develop 環境 を探すの困った
    • michizaneというものがあるらしいが、それなに？？
    • diamond 上で .m. を使った表記の名前(知りたかったのは メトリック定義ID
      • ne-sachirou: 正解ではなさそう…。その質問を文字通りにとるなら、正解は diamond 上のメトリックキー かな
• よほど精度の高いキーワードか脳内辞書を持ってないと情報に辿りつけない
• とりあえずシステムについて調べようとしたとき、Scrapboxを見て歩きだせる状態ではない
  • 例: michizaneを調べたいとき、「企画開発フローを見るといい」という発想はチーム初学者ではまず出ない
    • ne-sachirou: michizane を調べたいなら、企画開発フロー ではなく michizane を見るとよく、コンポーネント にたどり着けるといいなぁ
      • かういふ事になるもの問題の一端なんだらうと思って…
      • 企画開発フロー で書かれた文書の一覧も欲しいな…
        • 作った : 企画開発フローの一覧
• ページ数が多く、えぐいほどの量のページが出てくるが、何をみたらいいか分からない
• lufiabb: ドキュメント差分のレビューができない、意見を求められない
  • こう変えたいんだけどどう思うか？を聞く前に更新されてしまうので困る
• lufiabb: 議事録スタイルで意思決定がされても、後から参照したとき「結局どうなったのか」が分からない
  • 時系列でぜんぶ追っていくしかないが長すぎて読めない
• キーワード link が貼られないがちで
  • 関連項目を見逃す
  • 用語がブレがち
  • onk: 貼りすぎるのも関連リンク上手く使えなくなるので難しいなと思っている
• ルールがブレがち
  • そもそもルールあんまない
  • 複数チームが同時に触っててルールを制定するのがめんどくさいのもある
  • ブレを考慮して検索することになる。少々ブレてても曖昧検索してくれるが
• lufiabb: 検索がうまく機能しないのでページ全体から調べるが、そもそもロードされていないのでページ内検索ができない
  • 検索がうまく機能しない例
    • 今日のPWG会場を探したいが検索に入ってこない場合がある
      • ne-sachirou: 2024/11/1 みたいなので檢索する hack を身に着けてしまった…
    • 今週のデイリースクラム会場を探したいが..
• ne-sachirou: この文書、フロー寄りだと思ふけど日附け入れないんでせうか。など。これは問題の例として挙げた…。ストック寄りでしょ、って言ふ人もゐるだらう
  • どっちか議論してもたぶん議論内の力だけでは議論が終はらないと思ふ
  • lufiabb: 書いた日時に限らない、この時点の問題なのでストックのつもりでした、解決したら消せばいいと思ってる