Merge pull request #4790 from MicrosoftDocs/staging

merge latest changes to live

Author: sdwheeler

contributing/1-GET-STARTED.md

@@ -8,33 +8,34 @@ See below for details on how you can contribute to our technical documentation.
 
 ## Sign a CLA
 
-Before you can contribute to any PowerShell repositories, you must sign a [Microsoft Contribution Licensing Agreement (CLA)][cla].
-If you've already contributed to PowerShell repositories in the past, congratulations! You've
-already completed this step.
+Before you can contribute to any PowerShell repositories, you must sign a
+[Microsoft Contribution Licensing Agreement (CLA)][cla]. If you've already contributed to PowerShell
+repositories in the past, congratulations! You've already completed this step.
 
 ## Providing feedback on PowerShell documentation
 
-Point out errors, suggest changes, or request new topics by [creating an issue][new-issue] on the [PowerShell-Docs repository issues page][doc-issues].
+Report errors, suggest changes, or request new topics by [creating an issue][new-issue] on the
+[PowerShell-Docs repository issues page][doc-issues].
 
 Issues are reviewed regularly by members of the PowerShell documentation team. The issues are
-triaged, assigned, and addressed accordingly.
+triaged, assigned, and addressed as appropriate.
 
 ## Making minor edits to existing topics
 
 To [edit an existing file][edit-file], navigate to it and click the "Edit" button. GitHub will
 automatically create your own fork of our repository where you can make your changes. Once you are
-finished, save your edits and submit a [pull request][pull] to the *staging* branch of the [PowerShell-Docs][docs-repo]
-repository. After your pull request is created, someone on the PowerShell documentation team reviews
-your changes before merging them into the *staging* branch.
+finished, save your edits and submit a [pull request][pull] to the *staging* branch of the
+[PowerShell-Docs][docs-repo] repository. After your pull request is created, someone on the
+PowerShell documentation team reviews your changes before merging them into the *staging* branch.
 
 ## Making major edits to existing topics
 
-If you are making substantial changes, adding or changing images, or contributing a new article, you
-will need to create a GitHub fork and clone it to your computer. A fork is a GitHub-based replica of
-the main repository, under your GitHub account, that provides you with a working copy which you can
-use in isolation. You will create pull requests from your fork. Similarly, a clone is a local-based
-replica of the repository which, in this case, will be a clone of your fork. The clone allows you to
-work on Git repositories offline, and using more powerful native software/tools.
+If you are making significant changes, adding or changing images, or contributing a new article, you
+need to create a GitHub fork and clone it to your computer. A fork is a GitHub-based replica of the
+main repository, under your GitHub account, that provides you with a working copy which you can use
+in isolation. You create pull requests from your fork. Similarly, a clone is a local-based replica
+of the repository which, in this case, is a clone of your fork. The clone allows you to work on Git
+repositories offline, and using more powerful native software/tools.
 
 Here is the workflow for making major edits to existing documentation:
 

contributing/2-WRITING.md

@@ -1,8 +1,8 @@
 # Writing PowerShell documentation
 
 One of the easiest ways to contribute to PowerShell is by helping to write and edit documentation.
-All of our documentation hosted on GitHub is written using *Markdown*. Markdown is a lightweight
-markup language with plain text formatting syntax. Markdown forms the basis of our documentation's
+All the documentation hosted on GitHub is written using *Markdown*. Markdown is a lightweight markup
+language with plain text formatting syntax. Markdown forms the basis of our documentation's
 conceptual authoring language. Creating new articles is as easy as writing a simple text file by
 using your favorite text editor.
 
@@ -18,21 +18,21 @@ Here are some Markdown editors you can try out:
 
 To get started using Markdown, see [How to use Markdown for writing Docs](https://docs.microsoft.com/contribute/how-to-write-use-markdown).
 
-The Open Publishing System (OPS) is the platform used by docs.microsoft.com. OPS uses DocFX
-Flavored Markdown (DFM). DFM supports all GitHub Flavored Markdown (GFM) syntax and is compatible
-with CommonMark. There are some [differences between DFM and GFM][dfm-diffs] that can affect
-content preview in GitHub or your editor.
+The Open Publishing System (OPS) is the platform used by docs.microsoft.com. OPS uses DocFX Flavored
+Markdown (DFM). DFM supports all GitHub Flavored Markdown (GFM) syntax and is compatible with
+CommonMark. There are some [differences between DFM and GFM][dfm-diffs] that can affect content
+preview in GitHub or your editor.
 
 The default Markdown engine in OPS is built on the top of [markdig][]. This engine is based on the
-CommonMark specification and supports extensions for DocFX. In the latest version of the
-[CommonMark][] specification, many spacing rules have changed. Spaces are significant in Markdown.
-Don't use hard tabs in Markdown. For more detailed information about the Markdown specification,
-see the [Markdown Specifics](4-MARKDOWN-SPECIFICS.md) article.
+CommonMark specification and supports extensions for DocFX. In the latest version of the [CommonMark][]
+specification, many spacing rules have changed. Spaces are significant in Markdown. Don't use hard
+tabs in Markdown. For more detailed information about the Markdown specification, see the
+[Markdown Specifics](4-MARKDOWN-SPECIFICS.md) article.
 
 ## Creating new topics
 
-To contribute new documentation, check for issues tagged as ["in progress"][labels] to make
-sure you're not duplicating efforts. If no one seems to be working on what you have planned:
+To contribute new documentation, check for issues tagged as ["in progress"][labels] to make sure
+you're not duplicating efforts. If no one seems to be working on what you have planned:
 
 - Open a new issue and label it as "in progress". If you don't have rights to assign labels, add "in
   progress" as a comment to tell others what you're working on.
@@ -59,4 +59,4 @@ Read the [Style Guide](3-STYLE-GUIDE.md).
 [gfm-help]: https://help.github.com/categories/writing-on-github/
 [labels]: https://github.com/PowerShell/PowerShell-Docs/labels/in%20progress
 [gfm-task]: https://github.github.com/gfm/#task-list-items-extension-
-[dfm-diffs]: https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm
+[dfm-diffs]: https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#differences-between-dfm-and-gfm

contributing/3-STYLE-GUIDE.md

@@ -1,8 +1,6 @@
 # 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/).
 
@@ -11,86 +9,24 @@ For other writing style guidance, see the [Microsoft Style Guide](https://docs.m
 There are several variants of PowerShell.
 This table defines some of the different terms used to discuss PowerShell.
 
-| Terminology | Definition |
-| ----- | ----- |
-| PowerShell | This is the default. We are shipping PowerShell. The term PowerShell can be legitimately used to indicate any of the particular editions. This can be used to refer to the language, framework and default cmdlets, etc. |
-| PowerShell Core (PSCore) | PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of the platforms. |
-| Windows PowerShell | PowerShell built on .NET Common Language Runtime (CLR). Windows PowerShell ships only on Windows and requires the complete CLR. |
+- **PowerShell** - This is the default. We are shipping PowerShell. The term PowerShell can be
+  legitimately used to describe any edition of the product. This name can refer to the language,
+  framework, default cmdlets, etc.
+- **PowerShell Core** - PowerShell built on .NET Core Common Language Runtime (CoreCLR) for any of
+  the platforms.
+- **Windows PowerShell** - PowerShell built on .NET Common Language Runtime (CLR). Windows
+  PowerShell ships only on Windows and requires the complete CLR.
 
 In general, references to "Windows PowerShell" in documentation can be changed to "PowerShell".
 "Windows PowerShell" should **not** be changed when Windows-specific technology is being discussed.
 
-## Use semantic line breaks
-
-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
-  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.
-
-## Formatting syntax elements
-
-- PowerShell cmdlet names are [Pascal Cased][pascal-case].
-  Verbs are separated from nouns by a hyphen.
-  Always use the full Pascal Case name for cmdlets and parameters.
-  Avoid using aliases unless you are specifically talking about an alias.
-
-- Property, parameter, and class names should be **bold**
-
-- Within a paragraph, language keywords, cmdlet names, and variable references should be wrapped in
-  backtick (\`)   characters. For example:
-
-  The following code assigns the output of `Get-ChildItem` to the `$files` variable.
-
-  ```powershell
-  $files = Get-ChildItem C:\Windows
-  ```
-
-- 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 ...
-
-  > [!NOTE]
-  > Never use backticks or bold inside the brackets of a hyperlink. This is an exception to the previous
-  > rule.
-
-- When referring to a parameter by name, the name should be **bold**. When illustrating the use of
-  a parameter with the hyphen prefix, the parameter should be wrapped in backticks. For example:
-
-  > The parameter's name is **Name**, but it is typed as `-Name` when used on the command line as a
-  > parameter.
-
-- When referring to external commands (EXEs, scripts, etc.), the command name should be bold, all
-  lowercase (or capitalized if at the beginning of a sentence), and include the appropriate file
-  extension. For example:
-
-  > For example, on Windows systems, you can use the `net start` and `net stop` commands to start
-  > and stop a service. **Sc.exe** is another service control tool for Windows. That name does not
-  > fit into the naming pattern for the **net.exe** service commands.
-
-- When showing example usage of an external command, the example should be wrapped in backticks.
-  When there is a name collisions with an alias you must include the file extension in the command
-  example. For example:
-
-  > To start the spooler service on a remote computer named DC01, you type `sc.exe \\DC01 start spooler`.
-
-## Links
+## Hyperlinks
 
 - Avoid using bare URLs. Links should use Markdown syntax `[friendlyname](url-or-path)`
 - 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**.
+- Do not use backticks, bold, or other markup inside the brackets of a hyperlink.
 
 ### Understanding Docsets
 
@@ -100,7 +36,6 @@ PowerShell-Docs repo contains the following docsets:
 - developer - conceptual docs the PowerShell SDK
 - dsc - conceptual docs for DSC
 - gallery - conceptual docs for the PowerShell Gallery
-- jea - conceptual docs for Just-in-Enough Administration
 - reference - conceptual docs for using PowerShell and cmdlet reference docs
 - wmf - conceptual docs and release notes for WMF
 
@@ -169,7 +104,3 @@ This link only works on the webpage published to **docs.microsoft.com**.
 ## Next Steps
 
 See [Markdown Specifics](4-MARKDOWN-SPECIFICS.md).
-
-<!-- External URLs -->
-[pascal-case]: https://en.wikipedia.org/wiki/PascalCase
-[semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/