How to Improve Documentation by Writing Better PRs

  • Wed, Apr 6, 2022
  • 4-minute read

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:

  • Testing
  • 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

Be Concise

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.

For example:

- [ ] 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:

  1. Create a Markdown file named pull_request_template.md.
    You can save it in your repository’s root directory, in a docs directory, or as a hidden file inside the .github directory.
  2. Add your template’s content to the Markdown file and commit the changes to the repository.
  3. Now, when you open a new Pull Request, the template automatically loads for you to fill it.
Template Example

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:

  1. Capitalize the first word of your commit message
  2. Use present tense to describe the action (For example, Fix, Add, Revert)
  3. Do NOT end your message with a period (.)
  4. Include a reference to the issue
  5. Specify the type of change (feat, fix, style, refactor, test, docs)

Examples

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"
documentationagilepull requestscommit messagesjira