• View
• Edit
• History
• Print

Wikistyle

1. Use simple English.
   1. Choose simpler words when possible. Keep explanations concise:

      # Wrong: One should install the package by running $ doas pkg_add tcl
      # Right: $ doas pkg_add tcl
    # Avoid excessive jargon
    # Define the first use of uncommon abbreviations

1. Avoid slang

1. Be concise
   1. Wrong: You have now successfully turned from what was a comment into an actual parameter. You will need to uncomment and set any line that begins with semi-colon (;) character at the beginning of the line for any feature that you want. **Without removing that semi-colon that feature is either disabled or the defaults are used!**
   2. Right: Put a semi-colon (;) in front of a line to comment it out. Remove it to uncomment it.
   3. Wrong: I personally do not condone the notion of using FQDN that does not belong to you, as the consequences of going public with the named servers //can// potentially end up in lawsuits, for falsely misrepresenting a domain name.
   4. Right: Don't use a domain you don't own.
2. Where possible, use the active voice instead of the passive.
3. One paragraph for each new topic, and start each paragraph with a topic sentence
4. One main topic per page. If you have multiple topics, create multiple pages and link to those pages.
5. Avoid repeating too much unnecessary content that is already better described elsewhere.
   1. If content is described better on another page, link to that page instead of repeating material. This makes it easier to update and maintain content.
      1. For example, an article about ngircd should not spend too much time talking about the TCP/IP client-server model. Instead, link to that page.
6. Keep track of the difficulty level of each article and keep it in mind when writing.
7. Avoid markup that is purely cosmetic. Markup should be used to indicate the structure and meaning of content.
8. Show don't tell. If you want someone to read a man page, just link to it, don't tell him to type $ man <command>
9. It is OK to be opinionated, but defend it with evidence
   1. If there is a strong disagreement, create a separate page or a separate category.
10. Avoid formatting options that only make the text look nice; use tags that convey meaning
    1. Right: codeblocks, tables, Emphasis, Headings, Subheadings, indentation for quotes
    2. Wrong: Horizontal rules, indentation other than quotes
11. In case if there are multiple guides for same task, sort them. (for example sort IRC Clients based on OS)