DevDocs Contributions

The following topics are included in the Guide:

DevDocs contributions

What’s your area of expertise? Please share your knowledge with us! Contributions can take the form of completely new topics, changes and edits to existing documentation, or just good suggestions.

We have a template to make getting started easy. You can get a copy of the .md file on Github.

The language we use in our documentation is Markdown, which is a simple markup language that gets converted to HTML using Kramdown.

We also have a list of suggested topics, if you want to peruse and pick one that appeals to you.

If you write and contribute a full topic, we’ll put your name (or company’s name) at the top of the page, right under the title, and link it to your blog or website! And you’ll get your face and bio in the ring of honor as one of our featured contributors.

Use the fork & pull model to contribute to the Magento 2 DevDocs. This contribution model means that contributors maintain their own copy of the forked codebase (which can be easily synced with the main copy). The forked repository is then used to submit a request to the base repository to pull a set of changes (hence the phrase pull request).

The Magento DevDocs team reviews all issues and contributions submitted by the community. During the review we might require clarifications from the contributor. If you know what you want to write about, but you aren’t sure where within our multiple documents the topic should go, we can help you with the “info architecture” part.

Please refer to Magento Contributor Agreement for detailed information about the License Agreement. All contributors are required to submit a click-through form to agree to the terms.

Contribution guidelines

  1. Some common writing guidelines include:
    • Define what the goal of your topic is: what exactly do you want to teach the reader?
    • Make the title of your topic reflect the content.
    • Keep your sentences concise, and try to separate conceptual information from procedural steps.
    • Remember to use active voice (not passive), write in the present tense, and use a friendly tone in second person (for example, “You can now view the output…”)
    • Use Notes and even Warnings to alert readers to particularly important details.
    • Use cross-references to other topics if it is appropriate. We can help you with that syntax too, and the template has an example.
  2. Focus on the content and on creating useful information for your fellow Magento developers and community members, but do please take a few editorial passes at your work before submitting your topic and look for typos, formatting errors, or sentences that need clarifying.
  3. Familiarize yourself with the existing documentation; taking a look at what is already there will help you decide where your topic best fits and if there are other topics to which you might want to add cross-references in your topic.
  4. First, check the existing PRs and make sure you are not duplicating others’ work!
  5. For large contributions or changes that include multiple files, please open an issue and discuss first. This may prevent duplicate or unnecessary effort, and the DevDocs team can help find the best home for your new topics.

Fork a repository

To fork a repository on Github, do the following:

  1. Create or log in to your developemnt environment account on GitHub.

  2. Navigate to the DevDocs repository.

  3. Click Fork at the top right.

  4. Clone the repo into your development environment and then start writing and committing your changes. Optionally create a branch first if you plan to work on mulitple changes.

  5. You can build this site using Jekyll by following the instructions in our README.

Update the fork with the latest changes

As community and Magento writers’ changes are merged to the repository, your fork becames outdated and pull requests might result in conflicts. To see if your fork is outdated, open the fork page in GitHub and if at the top the message This branch is <number> commits behind magento:2.0. displays, it means your fork must be updated.

There are two ways to update your fork. The typical way is discussed in GitHub documentation. Make sure to update from the correct branch!

There is also a possibility to use the GitHub interface to do that. This is referred to as a reverse pull request. This method has the downside of inserting unnecessary information into fork commit history. On your fork GitHub page, click New pull request. You should see the following message:

There isn’t anything to compare.
magento:2.0 is up to date with all commits from <your fork>:2.0. Try switching the base for your comparison.

Click the base link and then click Create pull request. Provide a descriptive name for your pull request in the provided field.

Scroll to the bottom of the page and click Merge pull request, then click Confirm Merge.

Create a pull request

To create a pull request do the following:

  1. Push your changes to your forked repository on GitHub.

  2. In your forked repository, click New pull request.

  3. Be sure to create the pull request to the correct branch (the base). Our branches are numbered (2.0, 2.1, and so on). We don’t accept PRs to other branches, like gh-pages.

  4. Review the changes, then click Create pull request. Fill out the form, and click Create pull request again to submit the PR—that’s it!

After submitting your PR, you can head over to the DevDocs repository’s Pull Requests panel to see your PR along with the others. The DevDocs team will review your contribution, and get back with you if we have any questions. Once the final content is ready, we will merge your PR into the repo, and your work will be published to the repo and to devdocs.magento.com. If you write a whole topic, or make substantial contributions to an existing topic, we will add your name right below the title, linked to your blog or site!

Report an issue

If you find a typo or erroneous information in Magento DevDocs, you can either fix it with a PR (as described above) or you can simply report it by creating an issue in the DevDocs repository.

Before creating an issue, please check the existing issues to make sure that the issue wasn't already reported.

To add an issue:

  1. In the DevDocs repository’s Issues panel, click New issue on the right.
  2. Fill in the Title and issue description.
  3. Click Submit new issue.

Edit metadata

The .md (Markdown) file’s metadata is a set of key-value pairs (where the key is before the : and the value is after). The metadata section is located in the beginning of the file.

Example:

---
layout: default
group: install2
subgroup: Z_continue
title: Continue with your installation
menu_title: Continue with your installation
menu_node: parent
menu_order: 1
version: 2.0 github_link: install-gde/continue.md
---	

Definitions

Refer to the following table for a description of each key value pair in the metadata section of the .md file.

</tr>
Metadata Example Description
layout: default Selects the template Jekyll will use to render the .md file into HTML&CSS.
group: install2 Defines what book the file belongs to, that is, which left hand menu collection the file will show up in. Note that what you put here doesn't affect the horizontal menu. That is controlled by _/includes/navigation.html.
subgroup: Z_continue Defines what "chapter" or "subgroup" the file belongs to. Add the name of the subgroup here in each file that you want to collect into that subgroup.
title: Continue with your installation Sets the title of the page in the HTML meta and the main title on the page.
menu_title: Continue with your installation Sets the title as it appears in the menu.
menu_node: parent If set to parent, makes the file the link off of the subgroup header.
menu_order: 1 Sets the order files display. But not the order that subgroups appear in.
version: 2.0 github_link: install-gde/continue.md Gives you the name and location of the source file in github.

How to add a Contributor’s name to a topic

When a community member contributes an entire topic, or makes substantial improvements to an existing topic, we like to thank them by adding their name (or company name) right beneath the title of the topic, and link that name to their blog or web site.

In the metadata secion at the top of the file, just add these two entries:

  • contributor_name: <name_of_contributor>
  • contributor_link: <link_to_contributors_site_or_blog>

Thank you so much for adding your brilliance to the Magento DevDocs!!