Merge latest staging to live

contributing/STYLE.md

@@ -111,19 +111,94 @@ to get this output:
 
 ## Links
 
-* Avoid using bare URLs. Links should use MarkDown syntax `[friendlyname](url)`
-* Links should have a a friendly name when applicable, most likely the title of the linked page
-  * **Exception**: Links to non-Microsoft sites can be bare URLs
+* 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**.
 
-## Using relative links
+### Structure of links on docs.microsoft.com
+
+Content presented on docs.microsoft.com has the following URL structure:
+
+```
+https://docs.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]
+```
+
+Examples:
+
+```
+https://docs.microsoft.com/en-us/azure/load-balancer/load-balancer-overview
+https://docs.microsoft.com/en-us/powershell/azure/overview?view=azurermps-5.1.1
+```
+
+- **\<locale>** - identifies the language of the article (example: en-us or de-de)
+- **\<product-service>** - the name of the product or service being documented (example: powerShell, dotnet, or azure)
+- **[\<feature-service>]** - (optional) the name of the product's feature or subservice (for example, csharp or load-balancer)
+- **[\<subfolder>]** - (optional) the name of a subfolder within a feature
+- \<topic> - the name of the article file for the topic (example: load-balancer-overview or overview)
+- **[?view=\<view-name>]** - (optional) the view name used by the version selector for content that has multiple versions available (example: azurermps-5.1.1)
+
+### Linking to content in the same repo
 
-You should use relative links when linking to other content that is hosted on **docs.microsoft.com**.
 When the content is in the same repo, the relative links are simple to calculate.
-Note that the path to cmdlet reference is created by our publishing system.
-There are special rules for linking to reference topics from conceptual topics.
+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.
+
+```Markdown
+[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md)
+```
+
+Here is the live link:
+
+[about_Arrays](../reference/5.1/Microsoft.PowerShell.Core/About/about_Arrays.md)
+
+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.
+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.
+
+For example, the following markdown links to the Overview topic for Azure PowerShell.
+
+```Markdown
+[Overview of Azure PowerShell](/powershell/azure/overview)
+```
+
+Here is the live link:
+
+[Overview of Azure PowerShell](/powershell/azure/overview)
+
+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:
 
-\[TO DO\] - document special rules
+![alert boxes](./images/alert-boxes.png)
 
 ## Next steps
 
@@ -137,4 +212,4 @@ See [Formatting code blocks](FORMATTING-CODE.md).
 [links]: https://help.github.com/articles/relative-links-in-readmes/
 [gfm-spec]: https://github.github.com/gfm/
 [semantics]: http://rhodesmill.org/brandon/2012/one-sentence-per-line/
-[platyPS]: https://github.com/PowerShell/platyPS
+[platyPS]: https://github.com/PowerShell/platyPS

contributing/WRITING.md

@@ -1,7 +1,10 @@
 # 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 GitHub Flavored Markdown (GFM).
+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 conceptual authoring language.
+Creating new articles is as easy as writing a simple text file by using your favorite text editor.
 
 ## Markdown editors
 
@@ -12,16 +15,20 @@ Here are some Markdown editors you can try out:
 * [Atom](https://atom.io/)
 * [Sublime Text](http://www.sublimetext.com/)
 
-## Using GitHub Flavored Markdown
+## Get started using Markdown
 
-To get started using GFM, see GitHub's Help topics for [Writing on GitHub][gfm-help].
+To get started using Markdown, see GitHub's Help topics for [Writing on GitHub][gfm-help].
 
 **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.
 Do not use hard tabs in Markdown.
 For more detailed information about the Markdown specification, see the [GitHub Flavored Markdown Spec][gfm-spec].
 
+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.
+There are [differences between DFM and GFM][dfm-diffs] that can affect content preview in GitHub or your editor.
+
 ## Creating new topics
 
 If you want to contribute new documentation, first check for [issues tagged as "in progress"][labels]
@@ -53,4 +60,5 @@ Read the [Style Guide](STYLE.md).
 [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-
+[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

reference/3.0/Microsoft.PowerShell.Core/About/about_Functions.md

@@ -223,7 +223,7 @@ function Get-SmallFiles {
 ```
 
 For more information about the PSDefaultValue attribute class, see
-[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN.
+[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN.
 
 
 ### Positional Parameters

reference/4.0/Microsoft.PowerShell.Core/About/about_Functions.md

@@ -223,7 +223,7 @@ function Get-SmallFiles {
 ```
 
 For more information about the PSDefaultValue attribute class, see
-[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN.
+[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN.
 
 
 ### Positional Parameters

reference/5.0/Microsoft.PowerShell.Core/About/about_Functions.md

@@ -223,7 +223,7 @@ function Get-SmallFiles {
 ```
 
 For more information about the PSDefaultValue attribute class, see
-[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN.
+[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN.
 
 
 ### Positional Parameters

reference/5.1/Microsoft.PowerShell.Core/About/about_Functions.md

@@ -223,7 +223,7 @@ function Get-SmallFiles {
 ```
 
 For more information about the PSDefaultValue attribute class, see
-[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN.
+[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN.
 
 
 ### Positional Parameters

reference/6/Microsoft.PowerShell.Core/About/about_Functions.md

@@ -223,7 +223,7 @@ function Get-SmallFiles {
 ```
 
 For more information about the PSDefaultValue attribute class, see
-[PSDefaultValue Attribute Members](http://msdn.microsoft.com/library/windows/desktop/system.management.automation.psdefaultvalueattribute_members(v=vs.85).asp) on MSDN.
+[PSDefaultValue Attribute Members](https://msdn.microsoft.com/library/system.management.automation.psdefaultvalueattribute_members(v=vs.85).aspx) on MSDN.
 
 
 ### Positional Parameters

reference/6/Microsoft.PowerShell.Management/Set-Content.md

@@ -402,8 +402,6 @@ Otherwise, this cmdlet does not generate any output.
 
 ## NOTES
 
-You can also refer to Set-Content by its built-in alias, "sc". For more information, see [about_Aliases](../Microsoft.PowerShell.Core/About/about_Aliases.md).
-
 Set-Content is designed for string processing.
 If you pipe non-string objects to Set-Content, it converts the object to a string before writing it.
 To write objects to files, use Out-File.

reference/6/Microsoft.PowerShell.Utility/ConvertFrom-Clixml.md

@@ -0,0 +1,154 @@
+---
+ms.date:  2017-06-09
+schema:  2.0.0
+locale:  en-us
+keywords:  powershell,cmdlet
+online version:  
+external help file:  Microsoft.PowerShell.Commands.Utility.dll-Help.xml
+title:  ConvertFrom-Clixml
+---
+
+# ConvertFrom-Clixml
+
+## SYNOPSIS
+Converts an CLIXML string into new corresponding object in Windows PowerShell.
+
+## SYNTAX
+
+```
+ConvertFrom-Clixml -InputObject <string> [-IncludeTotalCount] [-Skip <UInt64>] [-First <UInt64>] [<CommonParameters>]
+```
+
+## DESCRIPTION
+The **ConvertFrom-CliXml** cmdlet converts a CLIXML string with data that represents Microsoft .NET Framework objects and creates the objects in Windows PowerShell.
+
+A valuable use of **ConvertFrom-CliXml** is to deserialize credentials and secure strings that have been serialized as secure XML by running the ConvertTo-Clixml cmdlet.
+For an example of how to do this, see Example 2.
+
+## EXAMPLES
+
+### Example 1: Import a serialized file and recreate an object
+
+```powershell
+$clixml = Get-Process | ConvertTo-Clixml 
+$Processes = ConvertFrom-Clixml $clixml
+```
+
+This command uses the ConvertTo-Clixml cmdlet to create a serialized copy of the process information returned by Get-Process.
+It then uses **ConvertFrom-Clixml** to retrieve the contents of the serialized string and re-create an object that is stored in the $Processes variable.
+
+### Example 2: Convert an encrypted credential object
+
+```powershell
+$CredXml = $Credential | ConvertTo-Clixml
+$Credential = ConvertFrom-CliXml $CredXml
+```
+
+The **ConvertTo-CliXml** cmdlet encrypts credential objects by using the
+[Windows Data Protection API](http://msdn.microsoft.com/library/windows/apps/xaml/hh464970.aspx).
+This ensures that only your user account can decrypt the contents of the credential object.
+
+In this example, given a credential that you've stored in the $Credential variable by running the Get-Credential cmdlet, you can run the **ConvertTo-CliXml** cmdlet to serialize the credential to a string.
+
+To deserialize the credential later, run the second command.
+This time, you are running ConvertFrom-Clixml to import the secured credential object into your script.
+This eliminates the risk of exposing plain-text passwords in your script.
+
+## PARAMETERS
+
+### -InputObject
+Specifies the CLIXML string to be converted to objects.
+You can also pipe the CLIXML string to **ConvertFrom-Clixml**.
+
+```yaml
+Type: string
+Parameter Sets: (All)
+Aliases: 
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: True (ByPropertyName, ByValue)
+Accept wildcard characters: False
+```
+
+### -First
+Gets only the specified number of objects.
+Enter the number of objects to get.
+
+```yaml
+Type: UInt64
+Parameter Sets: (All)
+Aliases: 
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Skip
+Ignores the specified number of objects and then gets the remaining objects.
+Enter the number of objects to skip.
+
+```yaml
+Type: UInt64
+Parameter Sets: (All)
+Aliases: 
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -IncludeTotalCount
+Reports the total number of objects in the data set (an integer) followed by the selected objects.
+If the cmdlet cannot determine the total count, it displays "Unknown total count." The integer has an Accuracy property that indicates the reliability of the total count value.
+The value of Accuracy ranges from 0.0 to 1.0 where 0.0 means that the cmdlet could not count the objects, 1.0 means that the count is exact, and a value between 0.0 and 1.0 indicates an increasingly reliable estimate.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: 
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](../../Microsoft.PowerShell.Core/About/about_CommonParameters.md).
+
+## INPUTS
+
+### System.String
+You can pipe a string that contains a path to **ConvertFrom-Clixml**.
+
+## OUTPUTS
+
+### PSObject
+**ConvertFrom-Clixml** returns objects that have been deserialized from the stored XML files.
+
+## NOTES
+* When specifying multiple values for a parameter, use commas to separate the values. For example, "\<parameter-name\> \<value1\>, \<value2\>".
+
+*
+
+## RELATED LINKS
+
+[Use PowerShell to Pass Credentials to Legacy Systems](http://blogs.technet.com/b/heyscriptingguy/archive/2011/06/05/use-powershell-to-pass-credentials-to-legacy-systems.aspx)
+
+[Securely Store Credentials on Disk](http://powershellcookbook.com/recipe/PukO/securely-store-credentials-on-disk)
+
+[Export-Clixml](Export-Clixml.md)
+
+[Import-Clixml](Import-Clixml.md)
+
+[ConvertTo-Clixml](ConvertTo-Clixml.md)
+
+