You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Nov 19, 2024. It is now read-only.
Share your knowledge with the community by contributing to Magento DevDocs!
4
4
You can contribute by creating an issue or pull request (PR) on our [DevDocs](https://github.com/magento/devdocs) GitHub repository.
@@ -9,19 +9,34 @@ Working through the backlog takes time, though, so we appreciate your patience.
9
9
10
10
## Rewards for contributions
11
11
12
-
DevDocs works with the Community Engineering teams and projects.
13
-
As you contribute PRs, you gain [Contribution Points](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#points).
12
+
DevDocs works with Magento Community Engineering teams and projects.
13
+
As you contribute PRs, you gain [Contribution Points](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#points). We track [Contributors](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributors.html#/individual-contributors) and [Maintainers](https://devdocs.magento.com/guides/v2.3/contributor-guide/maintainers.html) with Community Engineering.
14
14
15
-
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! We post your picture and a link to your GitHub account on the [Top recent contributors](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributors.html#/individual-contributors) page.
15
+
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!
16
16
17
-
## Prerequisites
17
+
## Get started
18
18
19
-
* Make sure you have a [GitHub account](https://github.com/signup/free). We recommend adding [Two-Factor Authentication](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#two-factor)(2FA) to your account. Partners are required to add 2FA protection when contributing to Magento repositories.
20
-
* Make sure you sign the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement).
21
-
* Check the [guidelines](#contribution-guidelines).
22
-
*[Fork](https://help.github.com/articles/fork-a-repo/) or [clone](https://help.github.com/articles/cloning-a-repository/) the [DevDocs repository](https://github.com/magento/devdocs). Remember to [sync your fork](https://help.github.com/articles/syncing-a-fork/) and update branches as needed.
19
+
23
20
24
-
**Note:** If you have not signed the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement), the PR will provide a link to complete. All contributors are required to submit the form and agree to the terms to complete it.
21
+
1. Make sure you have a [GitHub account](https://github.com/signup/free) with [Two-Factor Authentication](https://devdocs.magento.com/guides/v2.3/contributor-guide/contributing.html#two-factor)(2FA) to your account. Partners are required to add 2FA protection when contributing to Magento repositories.
22
+
1. Sign the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement).
23
+
1.[Fork](https://help.github.com/articles/fork-a-repo/) the [DevDocs repository](https://github.com/magento/devdocs). Remember to [sync your fork](https://help.github.com/articles/syncing-a-fork/) and update branches as needed.
24
+
1. Review the [DevDocs guidelines](#contribution-guidelines).
1. Create a new branch on your fork. Use a name that best describes the work, or references a GitHub issue number.
31
+
1. Edit or create markdown (`.md`) files in your branch.
32
+
1. When ready, push your branch to your fork.
33
+
1. Create a PR to the [magento/devdocs repo](https://github.com/magento/devdocs). Fill out as much info as possible and link any GitHub issues.
34
+
35
+
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, like `2.3.1-integration`.
36
+
37
+
The DevDocs team and Maintainers will review the PR and help with formatting and navigation.
38
+
39
+
**Note:** If you have not signed the [Magento Contributor Agreement](https://magento.com/content/magento-contributor-agreement), the PR provides a link. We require a signed form and agreement to the terms for contribution.
25
40
26
41
**Tip!** If you are not sure where to start contributing, check out our GitHub issues labeled [help wanted](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) and [good first issue](https://github.com/magento/devdocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
27
42
@@ -34,42 +49,38 @@ You can update existing or add new topics in their respective Magento 2 versione
34
49
The following guidelines may answer most of your questions and help you get started:
35
50
36
51
1. Check [existing pull requests](https://github.com/magento/devdocs/pulls) and make sure you are not duplicating work!
37
-
38
-
2. For large contributions or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This may further prevent duplicate or unnecessary effort.
39
-
40
-
3. Familiarize yourself with the existing documentation. Look through and search the guides to decide where to add your topics.
52
+
1. For large contributions or changes that include multiple files, [open an issue](#report-an-issue) and discuss it with us first. This may further prevent duplicate or unnecessary effort.
53
+
1.[Chunk many small/medium changes](#tips-for-writing-content) into one or two PRs. This helps us to efficiently and effectively facilitate your contribution.
54
+
1. Familiarize yourself with the existing documentation. Look through and search the guides to decide where to add your topics.
41
55
42
56
- The DevDocs team can find the best home for your new topics and add it to the navigation.
43
57
- 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.
44
58
45
-
## Write and submit PRs
46
-
47
-
1. Create a branch and start writing content in existing or new files.
48
-
49
-
1. 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.
59
+
## Tips for writing content
50
60
51
-
1. Use the following guidelines to help you with the writing process:
61
+
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.
52
62
53
-
- Define the goal of your topic. What exactly do you want to teach the reader?
54
-
- Make the title of your topic reflect the content.
55
-
- Keep your sentences concise and try to separate conceptual information from procedural steps.
56
-
- 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..."_.
57
-
- Use notes to alert readers about important details.
58
-
- 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.
59
-
- Need help with markdown? See our [templates](#templates).
63
+
Use the following guidelines to help you with the writing process:
60
64
61
-
1. Create a [pull request](https://help.github.com/articles/creating-a-pull-request/). Fill out as much info as possible and link any GitHub issues. DevDocs and Maintainers will review the PR. Watch for comments and requests for changes. We will merge the content when ready with appropriate labels.
65
+
- Define the goal of your topic. What exactly do you want to teach the reader?
66
+
- Make the title of your topic reflect the content.
67
+
- Keep your sentences concise and try to separate conceptual information from procedural steps.
68
+
- 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 on PR.
69
+
- 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..."_.
70
+
- Use notes to alert readers about important details.
71
+
- 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.
72
+
- Need help with markdown? See our [templates](#templates).
62
73
63
-
## Preview HTML locally
74
+
###Preview your work on local
64
75
65
-
To preview your changes in HTML output, follow the instructions in the [README](https://github.com/magento/devdocs/blob/master/README.md) to build the devdocs site locally using Jekyll.
76
+
Optional. To preview your changes in HTML output, follow the instructions in the [README](https://github.com/magento/devdocs/blob/master/README.md) to build the devdocs site locally using Jekyll.
66
77
67
-
## Templates
78
+
###Templates
68
79
69
80
We provide templates to help you started writing new content and understanding markdown formatting:
70
81
71
-
***General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
72
-
***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:
82
+
-**General topic template** - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/basic_template.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/basic_template.html): This is a template for writing any topic with example formats and styles.
83
+
-**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:
73
84
- First introduction topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-first.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-first.html): Introduction to a tutorial for prerequisites and listing steps
74
85
- Middle topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-middle.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-middle.html): Use for each step in a tutorial.
75
86
- Final step topic - [Markdown](https://github.com/magento/devdocs/blob/master/guides/v2.1/contributor-guide/templates/tutorial-template-last.md) | [HTML](https://devdocs.magento.com/guides/v2.3/contributor-guide/templates/tutorial-template-last.html): Use for the last step of the tutorial.
@@ -85,32 +96,34 @@ title: Continue with your installation
|`group`| Defines which guide the file belongs to and which left-hand menu collection the to use. |
94
-
|`title`| Sets the title of the page in the HTML meta and the main title on the page. |
101
+
| Property | Description |
102
+
| ------------- | ---------- |
103
+
|`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.|
104
+
|`title`| Sets the title of the page in the HTML meta and the main title on the page. |
95
105
96
106
## Report an issue
97
107
98
-
If you find a typo or erroneous information 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.
99
-
GitHub issues use templates for requested information. Enter as much information as you can including content corrections, steps to reproduce, command or code updates, or questions for clarifications.
108
+
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.
109
+
Enter as much information as you can including content corrections, steps to reproduce, command or code updates, or questions for clarifications.
100
110
101
111
**Note:** Check the [existing issues](https://github.com/magento/devdocs/issues) on GitHub to see if someone has already reported the issue.
102
112
103
113
You have a couple of options to enter an issue:
104
-
* Have general feedback? Create an issue on [GitHub DevDocs](https://github.com/magento/devdocs/issues/new/choose).
105
-
* Have feedback on a specific DevDocs page? Click the **Report an Issue** link at the top right of the page to report on the currently open topic.
106
-
* Have a Community code contribution that needs documentation? Create an issue to [request DevDocs content](https://github.com/magento/devdocs/issues/new?template=COMMUNITY_ISSUE_TEMPLATE.md).
114
+
- Have general feedback? Create an issue on [GitHub DevDocs](https://github.com/magento/devdocs/issues/new/choose).
115
+
- 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.
116
+
117
+
118
+
119
+
- Have a Community code contribution that needs documentation? Create an issue to [request DevDocs content](https://github.com/magento/devdocs/issues/new?template=COMMUNITY_ISSUE_TEMPLATE.md).
107
120
108
121
## Contact DevDocs
109
122
110
123
Have a question? Need help? Magento DevDocs, Maintainers, and other Contributors are available through:
0 commit comments