update to contributor guide (MicrosoftDocs#2500)

* update to contributor guide

* feedback fixes

* feedback fixes

CONTRIBUTING.md

@@ -4,7 +4,9 @@ Thank you for your interest in contributing to quality documentations.
 As an open source project, we welcome input and updates from the community.
 The following topics explain how to contribute to the PowerShell documentation.
 
-1. [Get started](./contributing/GETSTARTED.md)
-2. [Writing PowerShell documentation](./contributing/WRITING.md)
-3. [Style Guide](./contributing/STYLE.md)
-4. [Formatting Code blocks](./contributing/FORMATTING-CODE.md)
+1. [Get started](./contributing/1-GET-STARTED.md)
+2. [Writing PowerShell documentation](./contributing/2-WRITING.md)
+3. [Style Guide](./contributing/3-STYLE-GUIDE.md)
+4. [Markdown Specifics](./contributing/4-MARKDOWN-SPECIFICS.md)
+5. [Formatting Code blocks](./contributing/5-FORMATTING-CODE.md)
+6. [Updating Reference](./contributing/6-UPDATING-REFERENCE.md)

README.md

@@ -11,15 +11,16 @@ Welcome to the PowerShell-Docs repository, housing the official PowerShell docum
 
 ## Repository Structure
 
-Each folder in this repo publishes to [Microsoft Docs](https://docs.microsoft.com/powershell). The folders
-correspond to the following PowerShell assets:
+Each of the following top-level folders in this repo contain a DocSet that is published to [Microsoft Docs](https://docs.microsoft.com/powershell).
 
-- [/dsc/](https://docs.microsoft.com/powershell/dsc/) is  for the Desired State Configuration feature
+- [/developer/](https://docs.microsoft.com/powershell/developer/) is the future home of the PowerShell SDK documentation
+  - We are in the process of migrating this content from MSDN
+- [/dsc/](https://docs.microsoft.com/powershell/dsc/) is for the Desired State Configuration feature
 - [/gallery/](https://docs.microsoft.com/powershell/gallery) is for the [PowerShell Gallery](https://www.powershellgallery.com/)
 - [/jea/](https://docs.microsoft.com/powershell/jea/) is for the Just Enough Administration feature
-- [/reference/](https://docs.microsoft.com/powershell/scripting/) is for PowerShell conceptual topics
-  and module reference across versions 3.0, 4.0, 5.0, 5.1, and 6.0
-  - This content will be retrieved by the `Get-Help` cmdlet in the future
+- [/reference/](https://docs.microsoft.com/powershell/scripting/) is for PowerShell conceptual
+  topics and module reference across versions 3.0, 4.0, 5.0, 5.1, and 6.0
+  - This content is also the source of help content retrieved by the `Get-Help` cmdlet
 - [/wmf](https://docs.microsoft.com/powershell/wmf/readme) contains release notes for the Windows
   Management Framework, the package used to distribute new versions of PowerShell to previous versions of Windows.
 
@@ -30,8 +31,9 @@ into the *staging* branch.
 Please note that before you submit a pull request you must [sign a Contribution License Agreement](https://cla.microsoft.com/)
 to ensure that the community is free to use your submissions.
 
-For more information on contributing, read our [contributions guide](CONTRIBUTING.md).
-There is a draft [style guide](./contributing/STYLE.md) to review before making contributions.
+For more information on contributing, read our [contributor's guide](CONTRIBUTING.md).
+The contributor's guide contains detail information about how to contribute documentation,
+suggested tools, and style and formatting requirements.
 Please use the Issue and Pull Request templates to help keep documentation consistent across versions.
 
 ## Licenses

contributing/GETSTARTED.md → contributing/1-GET-STARTED.md

@@ -52,7 +52,7 @@ Here is the workflow for making major edits to existing documentation:
 
 ## Next steps
 
-See [Writing PowerShell documentation](WRITING.md).
+See [Writing PowerShell documentation](2-WRITING.md).
 
 <!-- External URLs -->
 [git-help]: https://help.github.com/

contributing/WRITING.md → contributing/2-WRITING.md

@@ -11,7 +11,6 @@ Creating new articles is as easy as writing a simple text file by using your fav
 Here are some Markdown editors you can try out:
 
 * [Visual Studio Code](https://code.visualstudio.com)
-* [Markdown Pad](http://markdownpad.com/)
 * [Atom](https://atom.io/)
 * [Sublime Text](http://www.sublimetext.com/)
 
@@ -21,9 +20,9 @@ To get started using Markdown, see GitHub's Help topics for [Writing on GitHub][
 
 **NOTE:** GitHub recently adopted the CommonMark specification (with GFM extensions) for its Markdown syntax.
 In the new specification, many spacing rules have changed.
-Spaces are significant in GFM.
+Spaces are significant in Markdown.
 Do not use hard tabs in Markdown.
-For more detailed information about the Markdown specification, see the [GitHub Flavored Markdown Spec][gfm-spec].
+For more detailed information about the Markdown specification, see the [Markdown Specifics](4-MARKDOWN-SPECIFICS.md) article.
 
 DocFX, used by OPS, supports DocFX Flavored Markdown (DFM).
 DFM is highly compatible with GitHub Flavored Markdown (GFM) and adds some functionality, including cross-reference and file inclusion.
@@ -38,7 +37,7 @@ If no one seems to be working on what you have planned:
 * 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.
 * Follow the same workflow as described above for making major edits to existing topics.
-* Do not edit the `TOC.md` or `TOC.yml` files (located in the top-level folder for each documentation set).
+* Do not edit the `TOC.yml` files (located in the top-level folder for each documentation set).
 * Create an issue requesting that your new article be added table of contents.
   Include a suggestion about where you think it show appear in the TOC.
   Someone on the PowerShell documentation team will make the appropriate changes to the TOC files.
@@ -54,11 +53,10 @@ you must apply the appropriate change to each version of the file.
 
 ## Next Steps
 
-Read the [Style Guide](STYLE.md).
+Read the [Style Guide](3-STYLE-GUIDE.md).
 
 <!-- External URLs -->
 [gfm-help]: https://help.github.com/categories/writing-on-github/
-[gfm-spec]: https://github.github.com/gfm/
 [labels]: https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress
 [gfm-task]: https://github.github.com/gfm/#task-list-items-extension-
 [dfm-diffs]: http://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm

contributing/STYLE.md → contributing/3-STYLE-GUIDE.md

@@ -1,5 +1,11 @@
 # Style guide for PowerShell-Docs
 
+This article provides some style guidance specific to the PowerShell-Docs content.
+There is some limited guidance on specific Markdown formatting.
+Markdown specifics are covered in the [Next steps](#next-steps).
+
+For other writing style guidance, see the [Microsoft Style Guide](https://docs.microsoft.com/style-guide/welcome/).
+
 ## Product Terminology
 
 There are several variants of PowerShell.
@@ -15,6 +21,7 @@ In general, references to "Windows PowerShell" in documentation can be changed t
 "Windows PowerShell" should **not** be changed when Windows-specific technology is being discussed.
 
 ## About_ file formatting
+
 We are changing the way we process about_ files.
 About_* files are being reformatted for the best compatibility across PowerShell versions and our publishing tools.
 For details, see [issue #1806][issue1806].
@@ -36,86 +43,40 @@ Basic formatting guidelines:
 Add a single newline after each sentence or a clause boundary near the 100 character limit.
 This simplifies the command-line output of diffs and history.
 
-* You must include semantic line breaks
-* Limit lines to 100 characters
-* If a sentence is longer than 100 characters, break the line at a clause boundary
+- You must include semantic line breaks
+- Limit lines to 100 characters
+- If a sentence is longer than 100 characters, break the line at a clause boundary
   near the 100 character limit
 
 For a good explanation of semantic line breaks, see [Semantic Linefeeds by Rhodes Mill][semantics].
 
 This is not currently adopted across all of PowerShell-Docs, but we will be working towards it over time.
 Feel free to help out.
 
-## Blank lines & Spaces vs Tabs
-
-Remove duplicate blank lines.
-Multiple blank lines render as a single blank line in HTML.
-Blank lines can also signal the end of a block in Markdown.
-There should be a single blank between Markdown blocks of different types (for example,
-between a paragraph and a list).
-
-**NOTE:** Spacing is significant in Markdown.
-Always uses spaces instead of hard tabs.
-Remove extra spaces at the end of lines.
-
-## Titles/Headings
-
-Only use [ATX headings][atx] (# style, as opposed to = or \- style headers).
-
-* Titles/headings should be surrounded by blank lines
-* Only the first letter of a title and any proper nouns in that title should be capitalized
-* Only one H1 per document
-
-When editing reference content, the H2s are prescribed by [platyPS][platyPS] and must not be added or removed.
-Adding or removing H2 causes a build break.
 
 ## Formatting syntax elements
 
-* PowerShell cmdlets are "[Pascal Cased][pascal-case]".
+- PowerShell cmdlets are "[Pascal Cased][pascal-case]".
   Verbs are seperated from nouns by a hyphen.
 
-* When talking about a cmdlet in paragraph, use \` to highlight cmdlet names
+- When talking about a cmdlet in paragraph, use \` to highlight cmdlet names
 
-* Property names and parameter names should be in **bold**
+- Property names and parameter names should be in **bold**
 
-* When writing an article (as opposed to reference content), the first instance of a cmdlet name should be a link to the cmdlet documentation.
+- When writing an article (as opposed to reference content), the first instance of a cmdlet name should be a link to the cmdlet documentation.
 
   For example:
 
   This [`Write-Host`](..\reference\6\Microsoft.PowerShell.Utility\Write-Host.md) cmdlet uses the **-Object** parameter to ...
 
-## Lists
-
-* Do not end list items with a period (unless they contain multiple sentences)
-* If your list contains multiple sentences, consider using a header 3/4/5 (as applicable) underneath your primary idea.
-
-If you want multiple lines within a single list element, format your list as follows:
-
-```markdown
-1. For the first element (like this one), insert a space after the 1.
-
-   To include a second element (like this one), insert a line break after the first and align indentations.
-   The indentation of the second element must line up with the first character after the numbered list marker.
-
-1. The next numbered item starts here.
-```
-
-to get this output:
-
-1. For the first element (like this one), insert a space after the 1.
-
-   To include a second element (like this one), insert a line break after the first and align indentations.
-   The indentation of the second element must line up with the first character after the numbered list marker.
-
-1. The next numbered item starts here.
-
 ## Links
 
-* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url-or-path)`
-  * **Exception**: Links to non-Microsoft sites can be bare URLs for transparency
-* Links must have a friendly name, usually the title of the linked topic
-* All items in the "related links" section at the bottom should be hyperlinked.
-* Use relative links when linking to other content that is hosted on **docs.microsoft.com**.
+- Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url-or-path)`
+ -* **Exception**: Links to non-Microsoft sites can be bare URLs for transparency
+- Links must have a friendly name, usually the title of the linked topic
+- All items in the "related links" section at the bottom should be hyperlinked.
+- Use relative links when linking to other content that is hosted on **docs.microsoft.com**.
+-
 
 ### Structure of links on docs.microsoft.com
 
@@ -141,7 +102,7 @@ https://docs.microsoft.com/en-us/powershell/azure/overview?view=azurermps-5.1.1
 
 ### Linking to content in the same repo
 
-When the content is in the same repo, the relative links are simple to calculate.
+When the content is in the same DocSet, the relative links are simple to calculate.
 The link target must be the path to the _Markdown file_ in the repo.
 For example, the following markdown links to the about_Arrays topic in this repo.
 
@@ -157,7 +118,7 @@ Note that the live link works within the GitHub view of this content.
 
 ### Linking to content in a different repo
 
-When the content is in a different repo, the relative links are more complicated.
+When the content is in a different DocSet, the relative links are more complicated.
 The link target must be the URL path to the _published article_ on **docs.microsoft.com**.
 The relative link starts with the **\<product-service>** portion of the URL as described above.
 You should omit the **[?view=\<view-name>]** portion unless you need to link to a specific version of the content.
@@ -175,34 +136,9 @@ Here is the live link:
 Note that the live link does not resolve within the GitHub view of this content.
 This link only works on the webpage published to **docs.microsoft.com**.
 
-## Markdown extensions supported by Open Publishing
-The following sections describe supported extensions in Open Publishing.
-
-### Note, warning, tip, important
-Use specific syntax inside a block quote to indicate that the content is a type of note.
-
-```Markdown
-> [!NOTE]
-> This is a note.
-
-> [!WARNING]
-> This is a warning.
-
-> [!TIP]
-> This is a tip.
-
-> [!IMPORTANT]
-> This is important.
-
-```
-
-And it will be rendered like this:
-
-![alert boxes](./images/alert-boxes.png)
-
-## Next steps
+## Next Steps
 
-See [Formatting code blocks](FORMATTING-CODE.md).
+See [Markdown Specifics](4-MARKDOWN-SPECIFICS.md).
 
 <!-- External URLs -->
 [pascal-case]: https://en.wikipedia.org/wiki/PascalCase