Specific rules to remember when writing documentation.

Consistency

It's important when writing to be consistent in all areas including, but not limited to, headings, code style, formatting, use of bold and italics. We acknowledge that as documentation has evolved, so has our writing style and not all of our documentation is consistent. As new documentation is written, it should be consistent.

Clarity

When writing we must remember to write for others and not just for ourselves. It's important to understand that jargon or acronyms can cause confusion, misunderstanding and a barrier for others who are not familiar with the terms. Avoid using jargon where you can, and only use acronyms once they have been clearly defined.

Code Style

Any code in documentation should conform to the Scripting and Best Practices Style Guide. The main points of this are:

• If referring to an executable, use choco, not choco.exe.
• Switches and parameters are simply called, options.
• Never use the force option (--force / -f) in scripts (or really otherwise as a default mode of use). Force is an override on Chocolatey CLI behavior. If you are wondering why Chocolatey CLI isn't doing something like the documentation says it should, it's likely because you are using force. Stop.
• Always use the full option name. If the short option is -n, and the full option is --name, use --name. The only acceptable short option for use in scripts is -y. Find option names in help docs online or through choco -? / choco [Command Name] -?.