Documentation Guidelines

From Kicksecure
< Dev
Jump to navigation Jump to search

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. Kicksecure 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 X in Kicksecure!".
  • 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.orgarchive.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 Kicksecure for user activities!".
    • "Multiple risks are faced by the user: deanonymization, browser fingerprinting and infection of the Kicksecure.".
  • 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:
    • "Kicksecure 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[edit]

Footnotes[edit]

Your support makes
all the difference!

We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!

Retrieved from "https://www.kicksecure.com/w/index.php?title=Dev/Documentation_Guidelines&oldid=77736"