Contribute to Documentation

Contribute to Documentation

Making contributions to MarkBind is not limited to code. You can also contribute to our documentation by fixing typos, improving the clarity of our explanations, or adding new content.

TLDR

  • Reviewing MarkBind documentation
  • Make modifications to the documentation
  • Make a pull request & verify the PR preview

Reviewing MarkBind Documentation

Assuming that you have completed the Explore MarkBind as a user task, you should have a working local MarkBind setup.

To review the documentation and make changes to it locally, you can:

  1. Open the MarkBind repository in your favorite code editor.
  2. Change directory to docs by running cd docs.
  3. Serve the documentation in development mode with markbind serve -d.
  4. Review both the user guide and the developer guide.

You may want to check if there are any open issues tagged with the a-Documentation label. These issues are usually related to documentation and may be a good place to start contributing for real!

Checkpoint

Ensure that you can serve the MarkBind documentation site in development mode. You should be able to browse the site at http://localhost:8080.

If port 8080 is in use, another port will be chosen. Refer to the console output for the exact URL address.
  • Browse the user guide to ensure that the content is rendered correctly.
  • Browse the developer guide to ensure that the content is rendered correctly.

Make Modifications to the Documentation

In the following steps, we will be fixing a hypothetical typo. You do not need to commit the changes or raise a PR, but understand the context and follow the steps to get a feel for the process.

Let's suppose we want to change the use of "Pop-Up" in our user guide to "Popup" (i.e. remove the hyphen).

These are the typical motivations for making documentation changes:

  • Fixing typos, grammar, or spelling mistakes when reading the documentation, which may not be code-related.
  • Keeping the documentation up-to-date with the latest changes in MarkBind, which may be code-related.
  • Improving the clarity of the documentation, which may or may not be code-related.

Before making any changes, go through the following steps:

  1. Check that the issue has been resolved in the latest master branch docs.
  2. Check that the issue has been raised, and if not, raise an issue.
    1. For trivial changes (like this one), you may skip this step.
    2. This step is important for more significant changes, as it allows the developer to propose changes and get feedback from the MarkBind team.

If the issue has been triaged and is ready to be worked on, we can proceed to make the changes. Since this is a trivial (and assuming correct) change, we will not be raising an issue and will proceed to make the changes directly.

  1. Check out a new branch from the latest master branch.
  2. Open the docs/userGuide/components/popups.md file.
  3. Replace Pop-Up/pop-up with Popup/popup in the file.
  4. Update the layout in docs/_markbind/layouts/userGuide.md to modify the site navigation item under Using Components from Pop-Ups to Popups.
  5. Search for Pop-Up/pop-up in the docs directory to ensure that there are no other occurrences of the word. Else, replace them as well.

Checkpoint

Check that the following are true:

  • The rendered site navigation item under Using Components in the user guide is now Popups
  • The word Pop-Up/pop-up has been replaced with Popup/popup in the rendered page.

Make a Pull Request & Verify the PR Preview

Once you have made the changes, commit them and push them to your forked repository. Now, you can make a pull request targeting the master branch of the MarkBind repository.

  1. Fill in the pull request template.
  2. Wait for the CI checks to pass.
    1. For first-time contributors, you may need to wait for the MarkBind team to approve your PR before the CI checks can run.
  3. Verify that the PR preview is working.
    1. The PR preview is generated by netlify/markbind-master/deploy-preview.
    2. You can find the link to the PR preview in the checks section of the PR. PR Checks Section
    3. Open the link to the PR preview and ensure that your changes are reflected in the rendered site
  4. Follow up with PR reviews and make changes as requested.

Since this is a hypothetical change, you do not need to raise a PR. You can refer to PR #1924 for an example.

Checkpoint

For actual documentation changes, check that the following are true:

  • The PR template has been filled in
  • The PR preview is working

Summary

In this task, you have learned how to make documentation changes to MarkBind!

While documentation changes are not as exciting as code changes, they are still important. In particular, our documentation is generated by MarkBind itself, utilizing the same features that we are documenting. This means that our documentation is a great place to discover and analyze how MarkBind is used!

Here are some additional tasks for you to try out:

  • Review a real documentation change (e.g issue #1772 was resolved in PR #1924 to improve the user guide)
  • Check if there are existing issues tagged with the a-Documentation label
    • If there are, try to resolve them!
    • If there are not, raise an issue when you discover a documentation bug or improvement (e.g make this bootcamp documentation better)!

When you are ready, move on to learn how to squash some bugs!

Explore MarkBind as a User

Fix a Bug