Taste Of cdoc on Day To Day
cdoc is About Blocking Your PR
cdoc is activated on your repo, all pull requests in that repo would have cdoc Github Check installed, which will show all Pull Requests in broken state.
This allows you to make documentation part of your process, as without process things do not happen and keep happening reliably over time when humans are involved.
So every PR is blocked now. How do we unblock it? By writing documentation and approving it!How To Write Documentation For A PR?
cdoc works under the assumption that the documentation for you code is stored in another git repository. For every code PR, we have to create a corresponding doc PR in the doc repo that is connected with this code repo.
FifthTry.com.
cdoc already.
Note: If you do not find the repository you are looking for, follow our setup instructions to install it.
Click on your repository, and you will see your PRs:
The idea of connection is declaring that “hey, this code that I just wrote, look at this PR, which contains the documentation for this code”.
And there you go!
Reviewing The Docs
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 it.
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 file 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:
You have to enter your Github username to approve. This is just a reminder that you have done your part in the process and things are indeed up to the documentation standard followed by your team.
We post on Github a comment on approver’s behalf that documentation has been approved and the PR can be merged now.
What If Code Does Not Require Documentation?
One frequent question we are asked is what if the code change is a minor bug fix, a minor refactor or such that it does not need any documentation?
We allow such case as well, in the UI where you were trying to connect documentation PR with your code PR, in this case you will not have any doc PR, so you can click on this link:
And There You Go
