|
1 | | -# Contributing to PowerShell Documentation |
| 1 | +# Contributor Guide |
2 | 2 |
|
3 | | -Thank you for your interest in PowerShell documentation! |
4 | | -See below for details on how you can contribute to our technical documentation. |
| 3 | +Thank you for your interest in contributing to quality documentations. |
| 4 | +As an open source project, we welcome input and updates from the community. |
| 5 | +The following topics explain how to contribute to the PowerShell documentation. |
5 | 6 |
|
6 | | ->For general information about getting started with Git and GitHub, see [GitHub Help](https://help.github.com/). |
7 | | -
|
8 | | -## Sign a CLA |
9 | | - |
10 | | -Before you can contribute to any PowerShell repositories, you must [sign a Microsoft Contribution Licensing Agreement (CLA)](https://cla.microsoft.com/). |
11 | | -If you've already contributed to PowerShell repositories in the past, congratulations! |
12 | | -You've already completed this step. |
13 | | - |
14 | | -## Providing feedback on PowerShell documentation |
15 | | - |
16 | | -You can point out errors, suggest changes, or request new topics by [creating an issue](https://help.github.com/articles/creating-an-issue/) on the |
17 | | -[PowerShell-Docs repository issues page](https://github.com/PowerShell/PowerShell-Docs/issues). |
18 | | - |
19 | | -Issues are reviewed regularly by members of the PowerShell documentation team, and are triaged, assigned, and addressed accordingly. |
20 | | - |
21 | | -## Writing PowerShell documentation |
22 | | - |
23 | | -One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation. |
24 | | -All of our documentation hosted on GitHub is written using [GitHub Flavored Markdown](https://help.github.com/articles/github-flavored-markdown/). |
25 | | - |
26 | | -## Making minor edits to existing topics |
27 | | - |
28 | | -To [edit an existing file](https://help.github.com/articles/editing-files-in-another-user-s-repository/), simply navigate to it and click the "Edit" button. |
29 | | -GitHub will automatically create your own fork of our repository where you can make your changes. |
30 | | -Once you're finished, save your edits and submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) to the *staging* branch of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. |
31 | | -After your pull request is created, someone on the PowerShell documentation team will review your changes before merging them into the *staging* branch. |
32 | | - |
33 | | -## Making major edits to existing topics |
34 | | - |
35 | | -If you are making substantial changes to an existing article, adding or changing images, or contributing a new article, you will need to manually create your GitHub fork, then clone the fork down to your local computer. |
36 | | -A fork is a GitHub-based replica of the main repository, under your GitHub account, which provides you with a working copy which you can use in isolation. |
37 | | -You will create pull requests from your fork. |
38 | | -Similarly, a clone is a local-based replica of the repository which, in this case, will be a clone of your fork. |
39 | | -The clone allows you to work on Git repositories offline, and using more powerful native software/tools. |
40 | | - |
41 | | -Here is the workflow for making major edits to existing documentation: |
42 | | - |
43 | | -1. [Create a fork](https://help.github.com/articles/fork-a-repo/) of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. |
44 | | -2. [Create a clone of your fork](https://help.github.com/articles/cloning-a-repository/) on your local computer. |
45 | | -3. Create a new local branch in your cloned repository. |
46 | | -4. Make changes to the file(s) you want to update in a Markdown editor. |
47 | | - See below for commonly used Markdown editors. |
48 | | -5. [Push your local branch](https://help.github.com/articles/pushing-to-a-remote/) to your fork. |
49 | | -6. [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) to the *staging* branch of the [PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repository. |
50 | | - |
51 | | -## Creating new topics |
52 | | - |
53 | | -If you want to contribute new documentation, first check for [issues tagged as "in progress"](https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress) to make sure you're not duplicating efforts. |
54 | | -If no one seems to be working on what you have planned: |
55 | | - |
56 | | -* Open a new issue and label it as "in progress" (if you are a member of the PowerShell organization) or add "in progress" as a comment to tell others what you're working on |
57 | | -* Follow the same workflow as described above for making major edits to existing topics. |
58 | | -* Edit the `TOC.md` topic (located in the top-level folder for each documentation set) to add your new topics to the table of contents. |
59 | | - Determine where your new topic belongs in the table of contents, and add a heading of the appropriate level, with a link to your topic (`[My topic title](relative path to my topic)`). |
60 | | - |
61 | | -## Markdown editors |
62 | | - |
63 | | -Here are some Markdown editors you can try out: |
64 | | - |
65 | | -* [Visual Studio Code](https://code.visualstudio.com) |
66 | | -* [Markdown Pad](http://markdownpad.com/) |
67 | | -* [Atom](https://atom.io/) |
68 | | -* [Sublime Text](http://www.sublimetext.com/) |
69 | | - |
70 | | - |
71 | | -## GitHub Flavored Markdown (GFM) |
72 | | - |
73 | | -All of the articles in this repository use [GitHub Flavored Markdown (GFM)](https://help.github.com/articles/github-flavored-markdown/). |
74 | | - |
75 | | -Some of the basic GFM syntax includes: |
76 | | - |
77 | | -* **Line breaks vs. paragraphs:** In Markdown there is no HTML `<br />` or `<p />` element. |
78 | | -Instead, a new paragraph is designated by an empty line between two blocks of text. |
79 | | - |
80 | | -> **Note**: Please add a single newline after each sentence to simplify the command-line output of diffs and history. |
81 | | -This is not currently adopted across all of PowerShell-Docs, but we will be working towards it over time. |
82 | | -Feel free to help out. |
83 | | - |
84 | | -* **Italics:** The HTML `<em>some text</em>` element is written as `*some text*` |
85 | | -* **Bold:** The HTML `<strong>some text</strong>` element is written as `**some text**` |
86 | | -* **Headings:** HTML headings are designated using `#` characters at the start of the line. |
87 | | - The number of `#` characters corresponds to the hierarchical level of the heading (for example, `#` = `<h1>` and `###` = ```<h3>```). |
88 | | -* **Numbered lists:** To make a numbered (ordered) list start the line with `1. `. |
89 | | - If you want multiple elements within a single list element, format your list as follows: |
90 | | -``` |
91 | | -1. For the first element (like this one), insert a tab stop after the 1. |
92 | | -
|
93 | | - To include a second element (like this one), insert a line break after the first and align indentations. |
94 | | -``` |
95 | | -to get this output: |
96 | | - |
97 | | -1. For the first element (like this one), insert a tab stop after the 1. |
98 | | - |
99 | | - To include a second element (like this one), insert a line break after the first and align indentations. |
100 | | - |
101 | | -* **Bulleted lists:** Bulleted (unordered) lists are almost identical to ordered lists except that the `1. ` is replaced with either `* `, `- `, or `+ `. |
102 | | -Multiple element lists work the same way as with ordered lists. |
103 | | -* **Links:** The syntax for a hyperlink is `[visible link text](link URL)`. |
104 | | -* **Link to another topic within the same docset:** A docset is a top-level folder in this repository |
105 | | - (for example, "dsc", "scripting"). |
106 | | - The syntax for a hyperlink to a topic within the same docset is `[topic title](relative path to topic)`. |
107 | | - For more information, see [Relative links in READMEs](https://help.github.com/articles/relative-links-in-readmes/). |
108 | | - To link to a topic in a different top-level folder, use the URL of the published page, as described above. |
| 7 | +1. [Get started](./contributing/GETSTARTED.md) |
| 8 | +2. [Writing PowerShell documentation](./contributing/WRITING.md) |
| 9 | +3. [Style Guide](./contributing/STYLE.md) |
0 commit comments