Skip to main content

How To Contribute Documentation Fixes

If you notice a problem in the Device42 documentation that you know how to fix, we appreciate contributions! Watch the video below, or read the article that follows to find out how to submit edits to our open source GitHub repository.

If you see a problem but you're not sure how to fix it, or don't have the time, hit the feedback button at the top of each page and our team will address it!

How Do I Edit a Document on GitHub? (Video)​

How Do I Edit a Document on GitHub? (Article)​

To edit a document on GitHub, you can create a pull request with your changes, and we'll review them before making them live on our website.

Start by clicking the "Edit this page" link at the bottom of the documentation page you want to edit.

You'll be prompted to sign in to GitHub if you're not already logged in to GitHub in your browser. When you're signed in, you'll be directed to the Device42 documentation repository.

Make a copy of the Device42 document repository by clicking the "Fork" button. Forking a repository creates a copy that you can safely make changes to without affecting the original.

In the dialog box that opens, click "Create fork".

Opening a Pull Request if You’ve Forked the Device42 Documentation Repository Before​

If you've previously forked the Device42 documentation repo and you're signed in to GitHub in your browser, clicking the "Edit this page" link will take you directly to the page on GitHub.

Once you've made changes to the document and you click "Commit changes...", the "Propose changes" modal window will include the message, "You can’t commit to main because it is a protected branch".

Now if you click the "Propose changes" button, your pull request will target your forked repository instead of the Device42 repository.

To target your pull request to the correct repository, do the following:

  • Click "compare across forks".

  • In the "base:" dropdown menu, select device42/device42-docs.

  • Click "Create pull request".

How To Make Changes to the Markdown File​

If you're not in "Edit" mode already, enter it by clicking the pen icon on the top-right of the preview window.

Markdown documents are plain-text documents with specific syntax to format text and add links and images. We'll outline how to add text and bullet points, and work with link and image syntax.

In this example, we've added some text to the document.

Bullet points are designated with a hash and space - before the content.

Links contain two parts: Text in square brackets followed by parentheses containing a URL or relative link. A link to the Device42 home page, for example, looks like [Device42](https://www.device42.com/).

Images begin with an exclamation mark (!) followed by alt text in square brackets and the path or URL of the image asset in parentheses. For example, ![Device42 logo](/assets/images/example.png). You can leave out alt text for the image like this: ![](/assets/images/example.png).

Here are some more tips for editing in Markdown:

  • In Device42 documentation, main headings are preceded with ## and secondary headings with ###.
  • Add ** before and after text to make it bold (**bold**) or _ to make it italic (_italic_).
  • Demarcate sections with * * * at the start and end of the section content.

Visit markdownguide.org for more information on Markdown syntax.

How To Submit Your Changes by Opening a Pull Request​

When you're done editing, you will commit your changes before opening a pull request.

  1. Review the changes you made in preview mode by clicking "Preview".

  1. Click the "Commit changes" button.

  1. In the modal window that opens, you can describe the changes you made (1). Select the "Create a new branch for this commit and start a pull request" option and give your branch a name in the text field below (2). Note that branch names in GitHub can't include spaces. To separate words in the name you give your branch, use a dash -. Click "Propose changes" to continue.

  1. Make sure that your pull request is being made to the main branch of Device42's repository and not your own forked copy. To double check that you're opening the pull request to the correct branch, click the "compare across forks" link on the "Comparing changes" page.

  1. In the "base repository" dropdown, change from your forked repository to device42/device42-docs.

  1. Click "Create pull request".

You'll be prompted to click "Create pull request" again in the dialog box that opens next.

  1. You'll see the details of your open pull request, including its number (#48 in the example).

Our team will review and test your proposed changes before they are made publicly visible.

For more information about the GitHub fork and pull model, refer to the GitHub documentation. If you need more assistance, please contact us.

Thank you for helping us improve our documentation and enhancing our user experience.