So code is usually written by one or more software developers. The documentation
can be written by the same developers, or by product managers.
The job of reviewing falls on someone else. The way code must be reviewed by a
third person before it should go to production, the documentation should also
be written by someone else other than the product manager/developer who wrote
One suggestion for this is the Quality Assurance/manual testing team, if you
have such a team. The quality team goes through a testing process and simplest
way to ensure docs are up to date is by asking QA team to look at docs (the
branch for your doc must be deployed somewhere), and rejecting the PR unless the
behaviour on UAT environment matches exactly what what is specified in the
documentation. This way any out of date screenshots, missing details in the
documentation can be spotted by QA department.
In absence of QA team, or along with them, especially if the changes are bit too
technical, the person who reviews the code can also review the documentation to
ensure the code and documentation changes are in line.
Wouldn’t the review process take too long? Isn’t there too much documentation?
In practice it does not, and this is why we recommend the doc in
git workflow, as the pull request against documentation usually is
same size or much smaller that pull request against code.
Note: For now our system requires only one approval. In future we will be adding
support for Github Code Owners
and support DOC-OWNERS to decide documentation of what part of code should be
reviewed by who.
Anyways, so the job here is pretty simple, review the code PR and doc PR, and
put your name behind it saying, “hey I have verified that the documentation for
the code indeed is complete, and up to our companies documentation standards”.
This part of putting your name behind things encourages people to review the
documentation properly, so there are no lapses.
To do this, find your PR on FifthTry once again, and click on Approve button: