Skip to content

Latest commit

 

History

History
137 lines (87 loc) · 10.2 KB

CONTRIBUTING.md

File metadata and controls

137 lines (87 loc) · 10.2 KB
Raw

Contribute to Magento DevDocs

Share your knowledge with the community by contributing to Magento DevDocs! You can contribute by creating an issue or pull request (PR) on our DevDocs GitHub repository. We welcome all types of contributions; from minor typo fixes to new topics.

Magento's tech writer team and Community Maintainers review issues and pull requests on a regular basis, and we do our best to address all issues as soon as possible. Working through the backlog takes time, though, so we appreciate your patience.

Rewards for contributions

DevDocs works with Magento Community Engineering teams and projects. As you contribute PRs, you gain Contribution Points. We track Contributors and Maintainers with Community Engineering.

If you write and contribute a full topic, we will add your name (or your company's name) at the top of the DevDocs page and link it to your blog or website!

Get started

Get started workflow

  1. Make sure you have a GitHub account with Two-Factor Authentication(2FA) to your account. Partners are required to add 2FA protection when contributing to Magento repositories.
  2. Sign the Magento Contributor Agreement.
  3. Fork the DevDocs repository. Remember to sync your fork and update branches as needed.
  4. Review the DevDocs guidelines.

Contribute docs

Contributing workflow

  1. Create a new branch on your fork. Use a name that best describes the work, or references a GitHub issue number.
  2. Edit or create markdown (.md) files in your branch.
  3. When ready, push your branch to your fork.

Create a pull request

Create a PR to the magento/devdocs repository. Fill out as much information as possible and link any GitHub issues.

In general, you should use master as the base branch when creating a PR. If your contribution is related to a release that is in progress, use a version-specific integration branch, such as develop.

Provide links to devdocs for the files you are changing. This is not required if the list is long.

If you are updating an example from source code, include a link to the file in the repository.

The DevDocs team and Maintainers will review the PR and help with formatting and navigation.

Note: If you have not signed the Magento Contributor Agreement, the PR provides a link. We require a signed form and agreement to the terms for contribution.

Tip! If you are not sure where to start contributing, check out our GitHub issues labeled help wanted and good first issue.

Contribution guidelines

Write content using kramdown, which is a simple markup language. We use kramdown, Liquid, and Jekyll to generate a static site hosted through GH Pages. Check Templates for examples of styles and markdown.

You can update existing or add new topics in their respective Magento 2 versioned directories (2.1, 2.2, 2.3, and onward). If you need help finding a directory for your content, we can help in your PR.

The following guidelines may answer most of your questions and help you get started:

  1. Check existing pull requests and make sure you are not duplicating work!

  2. For large contributions or changes that include multiple files, open an issue and discuss it with us first. This may further prevent duplicate or unnecessary effort.

  3. Chunk many small/medium changes into one or two PRs. This helps us to efficiently and effectively facilitate your contribution.

  4. Familiarize yourself with the existing documentation. Look through and search the guides to decide where to add your topics.

    • The DevDocs team can find the best home for your new topics and add it to the navigation.
    • If a topic has a symlink, you can remove it with Git commands and add a new file. Copy and paste a previous version of the topic to get started.

Tips for writing content

Focus on the content with useful information, code samples, and important notes for your fellow Magento developers and community members. Don't forget to review your work for typos, formatting errors, or sentences that need clarifying before opening a pull request.

Use the following guidelines to help you with the writing process:

  • Define the goal of your topic. What exactly do you want to teach the reader?
  • Make the title of your topic reflect the content.
  • Keep your sentences concise. Separate conceptual information from procedural steps.
  • Batch several small changes into a single pull request (instead of separate ones) to ensure your contributions get approved and merged quickly. Have several typo fixes across several areas of documentation? Batch them into one PR.
  • Remember to use active voice (not passive), write in the present tense, and use a friendly tone in second person. For example, "The log captures commands, output...".
  • Use notes to alert readers about important details.
  • Use cross-references to other topics if appropriate. We can help you with the syntax if it is not clear. The template provides an example you can use.
  • Need help with markdown? See our templates.

Preview your work on local

Optional. To preview your changes in HTML output, follow the instructions in the README to build the devdocs site locally using Jekyll.

Templates

We provide templates to help you started writing new content and understanding markdown formatting:

  • General topic template - Markdown | HTML: This is a template for writing any topic with example formats and styles.
  • Tutorial templates: These templates provide example formats and styles for step-by-step instructions (like how-tos). Each file adds navigation buttons when content is generated. Templates include:
    • First introduction topic - Markdown | HTML: Introduction to a tutorial for prerequisites and listing steps
    • Middle topic - Markdown | HTML: Use for each step in a tutorial.
    • Final step topic - Markdown | HTML: Use for the last step of the tutorial.

Edit metadata

The Markdown (.md) file's metadata is a set of YAML key-value pairs. The metadata section is located at the top of each file. For more info, see the Basic Template.

---
group: install2
title: Continue with your installation
---

Key-value pair reference:

Property Description
group Defines the topic's guide. Use the table of contents .yml file name. This loads your left-side navigation. We will help during the PR process to add new files to the .yml file.
title Sets the title of the page in the HTML meta and the main title on the page.

Report an issue

If you find a typo or errors in Magento DevDocs, you can either fix it with a pull request (as described above) or you can report it by creating an issue in the DevDocs GitHub repository. Enter as much information as you can including content corrections, steps to reproduce, command or code updates, or questions for clarifications.

Note: Check the existing issues on GitHub to see if someone has already reported the issue.

You have a couple of options to enter an issue:

  • Have general feedback? Create an issue on GitHub DevDocs.

  • Have feedback on a specific DevDocs page? Click the Give us feedback link at the top right of the page to report on the currently open topic.

    Report an issue

  • Have a Community code contribution that needs documentation? Create an issue to request DevDocs content.

Contact DevDocs

Have a question? Need help? Magento DevDocs, Maintainers, and other Contributors are available through:

Thank you for contributing your brilliance to Magento DevDocs!!