Last update: March 17, 2019. This website uses cookies. By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. More information

 Actions

Dev/Documentation Guidelines

< Dev

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

Preferred:

  • 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.


Grammatical Considerations

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 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.