NTFSSecurity/Docs/Contributing/03-Style-Guide.md

Style guide

Follow these rules so that the NTFSSecurity documentation reads as one consistent set of pages.

Language

• Write in American English, in the present tense, and in the active voice.
• Address the reader as "you".
• Keep sentences short, with one idea per sentence.
• Write product names as their owners do: PowerShell, Windows PowerShell, NTFS, Active Directory, GitHub.
• Format cmdlet names, parameter names, values, type names, paths, and code as code with backticks, for example Add-NTFSAccess -AccessRights Modify.
• Describe what the code does. Check every statement about behavior against the source code or a test run.

Examples

• Use the sample accounts CONTOSO\JohnDoe, CONTOSO\Domain Users, BUILTIN\Users, and BUILTIN\Administrators.
• Use sample paths below C:\Data.
• Use full cmdlet names, full parameter names, and full value names, for example FullControl instead of Full. Don't use aliases or positional parameters unless the example is about them.
• Test every example in a test folder before you publish it.
• Don't publish output that shows real computer, domain, or user names. Describe the result in a sentence instead.
• Say when an example needs an elevated session.

Cmdlet reference pages

Section	Content
SYNOPSIS	One sentence that starts with a verb in the third person, for example "Gets ..." or "Adds ...".
DESCRIPTION	What the cmdlet does, what it works on, how the parameter sets differ, defaults, and the module settings that affect it.
EXAMPLES	Two to four realistic tasks. Each example has a title, the command, and a sentence that explains the result.
PARAMETERS	"Specifies ..." for parameters that take a value and "Indicates that ..." for switches. Name the default when the parameter is omitted.
INPUTS and OUTPUTS	One sentence per type. Say when the cmdlet writes nothing by default.
NOTES	Required privileges, limitations, and differences between versions.
RELATED LINKS	Links to closely related cmdlet pages.

Conceptual pages

• Use one level 1 heading per page and sentence case for all headings.
• Start each page with a short introduction that says what the page covers.
• Wrap lines at 80 characters, except in tables, links, and code blocks.
• Link to the cmdlet reference instead of repeating parameter details.

Next steps

Read Markdown and platyPS specifics.