ソースコードはGithubで管理しているのにドキュメントは、Googleスプレッドシートなどで管理しているというプロジェクトが多くありますが、大抵の場合、ドキュメントは更新されずソースコードと乖離するというのがよくあることです。いっそのことドキュメントを作成するのをやめて、XPで開発するということもありかと思いますが、他の人への引き継ぐなどをかんがえるとまったくドキュメントを書かないわけにはいかないので、なんとなく書いているというパターンが多いと思います。
完結にドキュメントを記載する
昔読んだ「達人プログラマー」という本に最強の武器は、プレーンテキストだと書いてあったなと思い出しながら、さらっとドキュメント管理する方法はないのかなと思っていた。markdown + PlantUMLをつかったり、draw.ioで管理したりなどを繰り返しいましたが、どうもしっくりこないなという印象でした。
GithubでMarmaidがサポートされてことをきっかけに、markdown + mermaid でドキュメントを記載して、githubで管理する形式に完全に移行しました。
PRでソースコードとドキュメントを一緒にレビュー
実装をした際に、実装内容の説明をmarkdown、シーケンス図、クラス図などを一枚のMarkdownへ記載してあると、レビューする際にも確認がしやすく問い合わせが少なくなっている印象があります。下記がサーク管理アプリケーションに応募者の登録という機能を追加する際によく書くmarkdownの例です。
開発ドキュメントの乖離に悩んでいるかた、Markdown+MermaidでGithubでドキュメント管理するようにしてみてはいかがでしょうか。