NTFSSecurity/Docs/Contributing/02-Writing.md

# Write documentation

The NTFSSecurity documentation is written in Markdown and lives in the
`Docs` folder of the repository, where GitHub renders it. This page explains
how the documentation is organized and how to change it.

## Documentation structure

| Path | Content |
| --- | --- |
| `Docs/README.md` | Home page with features, requirements, installation, and the cmdlet list; GitHub shows it when you open the `Docs` folder |
| `Docs/Concepts.md` | Background on security descriptors, rights, inheritance, and privileges |
| `Docs/Examples.md` | Task-oriented examples |
| `Docs/Version-History.md` | Changes in 4.2.6 and earlier |
| `Docs/Cmdlets/*.md` | One reference page per cmdlet, in platyPS format |
| `NTFSSecurity/en-US/NTFSSecurity.dll-Help.xml` | Help file that `Get-Help` shows, generated from `Docs/Cmdlets` |
| `Docs/Contributing.md`, `Docs/Contributing/*.md` | This contributor guide |
| `README.md` | Front page of the GitHub repository |
| `CHANGELOG.md` | Changes since 4.2.6 |

When you add a page, link to it from `Docs/README.md` or from a related page,
so that readers can find it.

## Markdown editors

Any text editor works. These editors have good Markdown support:

- [Visual Studio Code](https://code.visualstudio.com) with the
  [markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
  extension
- [Sublime Text](https://www.sublimetext.com/)

To get started with Markdown, see
[How to use Markdown for writing Docs](https://learn.microsoft.com/contribute/content/markdown-reference).
Don't use hard tabs. For the rules that apply to this repository, see
[Markdown and platyPS specifics](04-Markdown-Specifics.md).

## Update the cmdlet reference

The pages in `Docs/Cmdlets` are [platyPS][platyps] Markdown files. platyPS
reads the parameter metadata from the module, so the syntax and the parameter
details always match the code. You write the synopsis, the description, the
parameter descriptions, the examples, and the notes.

When a cmdlet changes, build the module, import the build output, and update
the pages in Windows PowerShell 5.1. A Release build writes the module to
`NTFSSecurity\bin\Release`; the `before_build` and `build_script` steps in
`appveyor.yml` show the commands that the CI build uses:

```powershell
Install-Module -Name platyPS -RequiredVersion 0.14.2
Import-Module -Name .\NTFSSecurity\bin\Release\NTFSSecurity.psd1
Update-MarkdownHelp -Path .\Docs\Cmdlets
```

`Update-MarkdownHelp` updates the syntax and the parameter metadata and keeps
the text that you wrote. Fill in the description of every new parameter.

Use Windows PowerShell 5.1 for platyPS. In PowerShell 7.4 and later,
platyPS 0.14.2 adds the `-ProgressAction` common parameter to every page.

For a new cmdlet, create the page, replace every placeholder in it, and add
the cmdlet to the cmdlet list in `Docs/README.md`. Replace `Get-NTFSExample`
with the name of the new cmdlet:

```powershell
New-MarkdownHelp -Command Get-NTFSExample -OutputFolder .\Docs\Cmdlets
```

`Get-Help` shows the help file `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`,
which `New-ExternalHelp` generates from the pages and the build copies into
the module. Whenever you change a page in `Docs/Cmdlets`, generate the file
again and commit it together with the page:

```powershell
New-ExternalHelp -Path .\Docs\Cmdlets -OutputPath .\NTFSSecurity\en-US -Force
```

## Preview your change

GitHub renders the pages with GitHub Flavored Markdown. To preview a page
before you push it, open it in Visual Studio Code and press **Ctrl+Shift+V**.
In a pull request, the **Files changed** tab shows a changed page rendered
when you open its menu (**...**) and select **View file**.

## Check your change

Before you open a pull request, check the following:

- No page in `Docs/Cmdlets` contains a `{{ ... }}` placeholder.
- `Update-MarkdownHelp` doesn't change any page in `Docs/Cmdlets`. The build
  defined in `appveyor.yml` runs the same check.
- `New-ExternalHelp` doesn't change
  `NTFSSecurity\en-US\NTFSSecurity.dll-Help.xml`. The build runs the same
  check.
- The Pester tests in `Tests` pass. They test the module in
  `NTFSSecurity\bin\Release`, for example that `Get-Help` shows every page.
  The build runs them in Windows PowerShell 5.1 with Pester 5.7.1:

  ```powershell
  Install-Module -Name Pester -RequiredVersion 5.7.1 -SkipPublisherCheck
  Import-Module -Name Pester -RequiredVersion 5.7.1
  Invoke-Pester -Path .\Tests -Output Detailed
  ```

- All links work. The build checks them with `Get-MarkdownLink` from the
  MarkdownLinkCheck module:

  ```powershell
  Get-MarkdownLink -Path .\Docs -BrokenOnly
  ```

- Every example works. Test examples in a test folder, never on production
  data.

## Create new topics

Before you write a new topic, check the issues labeled
[Documentation][label-documentation] or [Help Wanted][label-help-wanted] to
make sure nobody else is working on it. If nobody is, open an issue that
describes the topic and say that you're working on it. Then follow the
workflow for larger changes in [Get started](01-Getting-Started.md).

## Next steps

Read the [Style guide](03-Style-Guide.md).

<!-- External URLs -->
[platyps]: https://github.com/PowerShell/platyPS
[label-documentation]: https://github.com/raandree/NTFSSecurity/labels/Documentation
[label-help-wanted]: https://github.com/raandree/NTFSSecurity/labels/Help%20Wanted