Our User Guide is open source and hosted in a public-facing repository on GitHub, where you can submit changes through pull requests (PRs). This open source approach to documentation has many advantages:
- An open and transparent process to cultivate the most helpful content about using Magento
- Continuous updates and publishing for content improvements and changes
- Ongoing collaboration between between customers, partners, our product teams, and our documentation team
Working with collaborative documentation
As a Magento user—regardless of whether you are an Adobe employee, partner, customer, or even a prospective customer—you have the opportunity to contribute to this documentation in several simple ways:
- Log a GitHub issue for a specific page
- Submit a quick edit where you see basic errors
- Author entire sections or pages, including graphics
The information in this topic outlines everything you need to know about how to interact with and contribute to this User Guide.
Log an issue
When you see a problem with one of our pages, such as a broken link, content error, or other item you can identify for fixing, let us know.
At the right of the page title, click Log an issue.
This opens the Issues tab in our GitHub repository. The URL of the page automatically populates in the summary field.
To log an issue, you will need to create a new account or log in to your existing GitHub account.
Enter a summary (or leave the default), write a short description of the issue, and then click Submit new issue.
Submit content changes
All of our content resides on GitHub, a well-known source control platform. Anyone can create a free GitHub account and make content changes and additions through the GitHub web UI. If you are a developer or know your way around Git source control and local build environments, you can choose to work with our source files that way.
For content contributions to be accepted and published, whether large or small, you must sign the Adobe Contributor License Agreement (CLA). This CLA is associated with your GitHub account. You will not need to sign it again.
Provide a quick edit
Making edits is a good way to fix small errors and omissions in the User Guide. If a page displays an edit link, you can make a quick fix yourself. When you edit the document, you send us a pull request (PR) to submit the fix/suggestion to us. Then we can review, approve, and publish the submitted change.
Open the User Guide page you want to edit or update.
To the right of the topic title, click Edit on GitHub.
This automatically opens the markdown source file in GitHub.
Click the pencil icon to edit the page.
If the pencil icon is not available, you need to login to your GitHub account or create a new account.
Make your changes in the web editor.
You can click the Preview changes tab to check the formatting of your change.
When your changes are complete, scroll to the bottom of the page.
Enter a summary and description for your commit (change record), similar to the following example:
Click Commit changes.
If you get a validation error message about signing a Contributor License Agreement (CLA), click Details to open the license agreement. Sign the agreement, if acceptable. Return to your pull request and continue.
That’s it! Magento Docs team members will review and merge your PR so that your changes can be included in our automated publishing process.
Author a new section or page
We recognize that our partners and customers have a great deal of knowledge from their real-world experiences with Magento. When you share your knowledge, the whole Magento community benefits. A new page based on how you solved an ecommerce requirement in Magento, for example, is a great addition to our User Guide.
Our GitHub wiki provides detailed information about authoring content, our markdown syntax, and page navigation.