Some teams keep their documentation along with source code, and require every pull request to update both code and documentation. The job of the person doing the PR review is to verify that code and docs are in sync.

The documentation in code has a few problems. People using this method usually only keep the documentation related to engineering in their code repository.

We believe documentation review should happen by the product and testing team as well. Assigning the job of code review to product managers or testing team is not feasible, and does not happen. End result is documentation is too biased and limited towards engineering aspects, and how does the product work is missing. Which means a new developer who joins still does not know how the product works overall and has to take sessions with product manager etc to understand how it works etc.

Another drawback of this approach is that documentation is in Git, and updating files in Git is hard for many product managers, QA team etc. Only developers are used to idiosyncrasies of working with Git, resolving conflicts, merging changes from each other etc.

While current cDoc does work with git and requires everyone to be comfortable with git, we at FifthTry are creating our own version control system and web based editing and change request system, where non developers can easily participate same process, but without having to learn many of the complexities that plagues git’s usability for non developers.

Some teams reserve some time for documentation at the end of feature development. They chose to not move on till documentation has also been updated.

This approach can be implemented with documentations stored in any software, not just Git. But this process depends on individual’s will. There is no process. Things can get neglected and no system warns you of that.

We believe things that rely on will alone, without process is prone to failure, and that is what we have found based on our interviews with tech teams. Things may start solid, but in the rush of deadlines etc, it’s too easy to forget to update docs, and once someone has moved on to the next feature, the details of last project start to become blur.