Jump to: navigation, search

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.