{{Header}}
{{title|title=
Documentation Guidelines
}}
{{#seo:
|description=Suggestions and recommendation for best authoring practices.
}} 
{{intro|
Suggestions and recommendation for best authoring practices.
}}
Authors are encouraged to use a formatting and grammatical style that is consistent with existing wiki entries and templates. Please refer to the suggestions below when completing entries.

Note: These suggestions are recommendations for best authoring practices and do not constitute absolute rules. {{project_name_long}} welcomes contributions from people who are willing to invest their time to help improve the wiki. Therefore, use this information as a guide only in the first instance.

<b>Wiki Formatting Style</b>

Preferred:

* Use preexisting wiki templates where possible.
* If editing templates, check edits suitably match existing wiki entries with the <i>/wiki/Special:WhatLinksHere/Template:NAME</i> command.
* Reference all sources and quotes.
* Do not submit copyrighted work without the necessary permission or attribution.
* Use <i>sudo</i> rather than <i>root</i> instructions.
* Standardize file path references in italics. For example: "Open <i>/etc/apt/preferences.d/debian-pinning.pref</i> in an editor.".
* Standardize command line function references in italics. For example: "Run <i>needrestart</i>.".
* Conservatively use bold text for warnings or other critical information. For example: "'''Warning:''' Do not use X in {{project_name_short}}!".
* Use mediawiki chapter / sub-chapter headings (where appropriate) for long instructions or to break up large blocks of text.
* Use bold text for titling where it is otherwise required.
* Number steps for long wiki entries where it is appropriate.
* Do not use colons in the last sentence preceding actual user steps; use a full stop / period. For example:
** "Complete the following steps.".
** Not "Complete the following steps:".
* Use <i>CodeSelect</i> for copy and paste instructions, for example command line functions.
* Use <i>blockquote</i> for quoting text verbatim.
* Use <i>code</i> for highlighting special instructions, for example navigating browser menus, application settings and so on.
* Use <i>pre</i> for other highlighted text that does not require special formatting for cut and paste purposes.
* Use <i>ref</i> for footnoting minor issues.
* Use <i>br</i> for necessary breaks in block-quoted or other text.
* Use <i>box</i> for special text or instructions that need to be differentiated from the rest of the entry.
* Embed internal or external links for important issues for reader consideration. For example:
** "Read and apply the [[System Hardening Checklist]].".
** "This should not be confused with [https://en.wikipedia.org/wiki/Hardware_Trojan hardware/circuit trojans].".
* Use tables where possible for large wiki entries defining / discussing / comparing multiple variables, categories, features, options or other data.
* Use recent screenshots if it is appropriate and feasible for the wiki entry.
* Use definite, specific, concrete language and instructional steps to minimize reader confusion.
* Use specific examples like sample configuration files, system messages and commands when writing instructional steps to minimize reader confusion.
* Write for an audience with an expected high-school graduate education. Use https://simple.wikipedia.org as a guide for the intended audience.

<b>Grammatical Considerations</b>

Preferred:

* American English. For example, American spelling and phrasing.
* Spell-checked text.
* Check hyphenation use is appropriate.
* Avoid "e.g.", "i.e.", "etc." and other abbreviations. Instead use "For example / like ", "that is", "and so on".
* Capitalize and check the accuracy of acronyms.
* Do not use acronyms without first defining them.
* Use double, rather than single quotation marks in general.
* Avoid apostrophes or contractions in general. For example: "It is" not "It's".
* Avoid the use of pronouns. For example: I, you, your, me, us, we, he, she, they, mine, ours, yourself, myself, themselves and so on. Use "the" instead.
* Capitalize the first letter of words in chapter headings and titles (in general).
* Capitalize the first letter of the first word in bullet points that form complete sentences.
* End bullet points with a full stop / period (in general).
* Capitalize the first letter of words following colons, except for sentences forming lists or expounding on an idea in the first portion of the sentence. For example:
** "Warning: Do not use the {{project_name_gateway_long}} for user activities!".
** "Multiple risks are faced by the user: deanonymization, browser fingerprinting and infection of the {{project_name_workstation_long}}.".
* Capitalize proper nouns.
* Avoid overuse of brackets and parentheses. Either write the text in a full sentence or footnote minor points.
* Write in the active voice.
* Avoid slang or common English terms.
* Avoid shortening words and use the full spelling, for example "distributions" vs "distros".
* Make sure all referents are clear, for example "This theory...", "That checked option...", "Those settings..." and so on.
* Avoid long sentences. Break ideas into simpler, shorter sentences for clarity.
* Avoid run-on sentences. For example:
** "Firefox is hardened against fingerprinting. It is patched to prevent leaking of several attributes."
** Not "Firefox is hardened against fingerprinting, it is patched to prevent leaking of several attributes."
* Avoid sentence fragments. For example:
** "{{project_name_short}} helps to prevent SUID binaries.".
** Not "Prevents SUID binaries.".
* Use declarative statements in preference to rhetorical statements. For example:
** "Few users are likely to set a proxy with Firefox.".
** Not "How many users are likely to set a proxy with Firefox?".
* Write statements in the positive, rather than negative form. For example:
** "What is happening...".
** Not "What is not happening...".
* Nouns and verbs are preferable to adjectives and adverbs.
* Avoid the use of qualifiers e.g. pretty, very, rather, little and so on.
* Omit needless words to improve sentence clarity.

= See Also =
* [[Dev/Documentation Markup Format Converters]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Development]] [[Category:Design]]