How to Improve Documentation by Writing Better PRs
Technical Documentation and Agile
Very often, when I join a new team and I ask if there’s any existing documentation, the answer tends to be: “No, we don’t have docs.” And most of the time this is not true.
Agile teams that don’t have a technical writer assigned tend to think that they don’t have any documentation or very little documentation in place. But the reality is that they have many information lying around in Pull Requests or Jira tickets; or even commit messages.
Granted, it might not be the best-written documentation nor the best-organized, but it is useful, and most importantly, it can improve, helping to generate better internal documentation more easily.
Writing Better Pull Requests
Writing better Pull Request descriptions not only can help you or your team having better documentation, it can also help in other tasks, suuch as:
- Knowledge sharing
- Reduce time to review, approve, and merge (More effieciency)
- Improve communication skills
How to Write Better Pull Requests
To write good PR descriptions:
- Be concise
- Have a checklist
- Use a template
Briefly describe what the PR does. Verify you cover the following:
- What is this PR for?
- What does the code do? What are the changes you applied?
- Is it a fix or a new feature? (You can link a Jira issue)
- How can I test this PR?
Have a Checklist
To make the process of creating a PR or reviewing a PR easier, you can use checklists to ensure all the basic elements of the PR description are covered and the reviewer doesn’t forget to review any of those.
- [ ] I have performed a self-review of my code - [ ] I have added unit tests and integration tests (if applicable) - [ ] I have confirmed that the code builds without errors or warnings
Similarly, you can use checklists for the different sections of the PR. At the end of this post you can find a template example with checklists.
Use a Template
Using a template makes it easier for everyone in your project to create good PRs and to have a consistent way of documenting changes to the code.
To create a template in GitHub:
- Create a Markdown file named
You can save it in your repository’s root directory, in a
docsdirectory, or as a hidden file inside the
- Add your template’s content to the Markdown file and commit the changes to the repository.
- Now, when you open a new Pull Request, the template automatically loads for you to fill it.
Below you can find a Pull Request example for you to use. You can modify it as you consider necessary for your projects:
# Description Briefly describe what this PR does. What does the code do? What are the changes you applied? ## Issues - Fixes # issue - Related issues: # ## Type of change Select the options that apply and delete the ones that are not relevant. - [ ] Bug fix (non-breaking change) - [ ] New feature (non-breaking change | adds new functionality) - [ ] Breaking change (fixes existing issue but causes existing features to not work as expected) # Tests Describe the tests required to verify the changes. - [ ] Test A Steps to reproduce bug or test the feature - [ ] Test B Steps to reproduce bug or test the feature # Checklist Before submitting your PR, make sure you have: - [ ] I have performed a self-review of my code - [ ] I have added unit tests and integration tests (if applicable) - [ ] I have confirmed that the code builds without errors or warnings # Screenshots Include any relevant screenshots (UI)
Writing Better Commit Messages
Writing a good commit message can seem like an extra step and can feel like an unnecessary hassle. But in the long run it can help others, and even yourself, to understand the changes made to the code, and why some changes were required at every stage of the development process.
Tips to write useful commit messages:
- Capitalize the first word of your commit message
- Use present tense to describe the action (For example,
- Do NOT end your message with a period (
- Include a reference to the issue
- Specify the type of change (
Some examples of good commit messages:
git commit -m "feat: Add login functionality - Closes ABC-123"
git commit -m "fix: Fix bug that prevented users from selecting two food options - Closes BUG-345"