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. Whonix ™ 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.
Wiki Formatting Style
- Use preexisting wiki templates where possible.
- If editing templates, check edits suitably match existing wiki entries with the /wiki/Special:WhatLinksHere/Template:NAME command.
- Reference all sources and quotes.
- Do not submit copyrighted work without the necessary permission or attribution.
- Use sudo rather than root instructions.
- Standardize file path references in italics. For example: "Open /etc/apt/preferences.d/debian-pinning.pref in an editor.".
- Standardize command line function references in italics. For example: "Run needrestart.".
- Conservatively use bold text for warnings or other critical information. For example: "Warning: Do not use other browsers in Whonix-Workstation ™!".
- 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 CodeSelect for copy and paste instructions, for example command line functions.
- Use blockquote for quoting text verbatim.
- Use code for highlighting special instructions, for example navigating browser menus, application settings and so on.
- Use pre for other highlighted text that does not require special formatting for cut and paste purposes.
- Use ref for footnoting minor issues.
- Use br for necessary breaks in block-quoted or other text.
- Use box 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:
- 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.
- 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 Whonix-Gateway ™ for user activities!".
- "Multiple risks are faced by the user: deanonymization, browser fingerprinting and infection of the Whonix-Workstation ™.".
- 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:
- "Tor Browser is hardened against fingerprinting. It is patched to prevent leaking of several attributes."
- Not "Tor Browser is hardened against fingerprinting, it is patched to prevent leaking of several attributes."
- Avoid sentence fragments. For example:
- "Whonix-Workstation ™ helps to prevent IP address leaks.".
- Not "Prevents IP address leaks.".
- Use declarative statements in preference to rhetorical statements. For example:
- "Few users are likely to set a proxy with Tor Browser.".
- Not "How many users are likely to set a proxy with Tor Browser?".
- 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.