5.3 KiB

Raw Blame History

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 with the markdownlint extension
Sublime Text

To get started with Markdown, see How to use Markdown for writing Docs. Don't use hard tabs. For the rules that apply to this repository, see Markdown and platyPS specifics.

Update the cmdlet reference

The pages in Docs/Cmdlets are 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:

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:

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:

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:
```
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:
```
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 or 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.

Next steps

Read the Style guide.

5.3 KiB Raw Blame History