# Writing Tips and Suggestions

The writing rules and tips listed in this section are more suggestions than concrete rules, but they are important to make documentation clear, concise, effective, absorbing, and comprehensible. These suggestions and guidelines are meant to help anyone improve their writing skills.

Good Documentation Requires Relentless Editing
  If you really want to produce great documentation, it needs to be proofread and edited. No matter how talented a writer happens to be, it is nearly impossible to avoid mistakes on the first attempt.
  Tips for proofreading and editing:
  - It is often a good idea to write all of your text, then take a break from it, and return to proofread and edit it later with fresh eyes and ideas.
  - When proofreading your text, shorten, delete, and rewrite anything that does not add to its meaning.
  - It is also a good idea to have someone else review your documentation because when you read something you wrote yourself, you know what you meant to write, so it is really easy to just skip over typos or missing words.
  - If you are editing your own work, changing the indent structure or font size can help you recognize mistakes that were previously unnoticed.
Basic Writing Rules
  The following rules are suggestions in regards to general writing standards:
  Complete Sentences
    Rules or Suggestions: Except in extraordinary circumstances, sentences should always be complete. Proofread your work carefully to spot sentence fragments that are written as if they are complete sentences.
  Redundancy
    Rules or Suggestions: It is usually a good practice to avoid redundancy, or extra unnecessary words, in your writing. Redundancy makes your writing less effective because it makes the reader waste time and attention re-reading information that was already provided. The point of your writing should be to provide all the necessary information in the most precise and effective manner possible. There are times when it is good to use redundancy for emphasis, but in all other situations it is best to avoid it.
    Examples of redundant phrases to avoid in technical writing:
    - "add an additional" - The word "additional" is redundant.
    - "during the course of" - The words "course of" are repetitive.
    - "end result" - The word "end" is not needed.
    - "final outcome" - The word "final" is repetitive.
    - "in order to" - The words "in order" are not needed.
    - "merge together" - The word "together" is redundant.
    - "since the time you last" - You can omit "the time" and just use "since you last. This also applies without the word "last". For example, "since the time you opened the file" should be "since you last opened the file".
    - "still remains" - The word "still" is unnecessary.
    - "unintentional mistake" - All mistakes are "unintentional", so that word is redundant.
    - "variety of different" - If there is a variety of something, it is implied that they are different, thus "different" is redundant.
    - Avoid using unnecessary adverbs that are NOT specifically used for some sort of emphasis (for example, "very", "little", "pretty", "extremely").
  Run-on Sentences
    Rules or Suggestions: A run-on sentence is one that joins clauses that could each stand on its own as a sentence without any punctuation or words to link them. Fused sentences must be either divided into separate sentences or joined by adding conjunctive words or punctuation. Always consider the general flow and the length of the sentences to decide whether to separate them or add conjunctions.
  Structure of Paragraphs
    Rules or Suggestions: The ideas in all the sentences in a paragraph should be interconnected. If you introduce a completely new thought, you need to start a new paragraph. The ideas should also flow in proper sequence so that you do not confuse the reader. Also, do not make the paragraphs too long because your readers might get disinterested and feel like they are inundated with too much information at once.
  Structure of Sentences
    Rules or Suggestions: Try to avoid starting a sentence with one kind of structure and then changing to another later in the sentence. Doing so can confuse your readers.
  Structure of Topics
    Rules or Suggestions: Make sure the whole topic has a good flow. Usually, you will want to introduce the concept, then provide the specific content that will provide the reader with all the information they need, then wrap it up with some sort of conclusion that summarizes everything or clearly indicates the end of the topic.
  Transitions
    Rules or Suggestions: Each paragraph should transition smoothly from the preceding paragraph. Without good transitions, the reader will end up backtracking repeatedly and will often become confused or frustrated.
Basic Technical Writing Rules
  The following rules are suggestions in regards to technical writing standards:
  Ambiguity
    Rules or Suggestions: One of the most important things in technical writing is to make sure the information that you write is very clear. Use the following rules to help avoid confusion:
    - Always proofread your writing carefully to identify possible ambiguity.
    - It is also always a good idea to have someone else proofread your writing because it may seem clear to you, but if it is ambiguous to them, in any way, then it is probably also ambiguous to your normal audience.
    - Be careful when using pronouns ("this, "these", "it"). Always ask yourself if there is any chance that the reader will not know exactly what items the pronouns are referencing. See the Vague Pronouns section in the Grammar Rules for more specific information.
  Audience
    Rules or Suggestions: Always consider who your audience might be for your specific topic. Once you identify who you are writing it for, ask yourself what they need to know and make sure you include everything that audience needs to know.
  Avoid Fancy Words
    Rules or Suggestions: The best writing is simple and concise, with the relevant ideas delivered in a clear and direct manner. Avoid using fancy words that might be perceived as pretentious or more elaborate than necessary. Your audience will appreciate reading words that are simple and to the point. They care about your content being clear and accurate, not how big your vocabulary is.
  Avoid Passive Voice
    Rules or Suggestions: Particularly in technical writing, you should avoid using a passive voice whenever possible. Passive writing comes across as sounding weak and ambiguous, while using in an active voice makes your writing seem more alive and clear. Basically, passive voice happens when the object of a sentence is placed in the beginning of a sentence instead of the end. In other words, the object becomes the subject. For example, "I mailed the letter" becomes passive if it is changed to "The letter was mailed by me".
    How to recognize a Passive Voice sentence
      The two most basic things to ask yourself are:
      - Is the object in the subject position?
      - Can I add "by [so-and-so]" to the end?
      Also, keep this in mind: All passive sentences include a form of the verb "to be" (such as "was", "were" or "is"), BUT not all sentences that have those verbs are passive. It is easy to recognize sentences that include a form of "to be" but you need to ask yourself the two questions above to determine if it is in the passive voice.
    Examples from the UG:
      Passive voice: The New Document wizard allows you to select custom templates that were created in previous sessions by you or other users. [INCORRECT]
      Active voice: The New Document wizard allows you to select custom templates that you or other users created in previous sessions. [CORRECT]
  Avoid Using Figures of Speech
    Rules or Suggestions: Always avoid figures of speech, such as similes and metaphors.
  Consistency
    Rules or Suggestions: By nature, technical documentation is certainly not much fun to read and it might seem that meticulous consistency would make it even more boring. That logic might true for general writing, but most of the time the only reason why people read technical documentation is because they are stuck and need to figure out how to do something specific. Using meticulous consistency in technical writing will allow the user to find information quickly and help them to understand it better.
  Contractions
    Rules or Suggestions: Contractions are appropriate only for conversational use and for informal writing, but never for technical writing. Avoid using them in the User Guide.
  Include Links to Other Documentation
    Rules or Suggestions: Include links to other pertinent sections of the documentation (or other resources) whenever possible. You want to make it as convenient as possible for the users to navigate to other sections, topics, or resources that might help them to find the information they need.
  Make Important Content Noticeable
    Rules or Suggestions: Use various structural elements to make topics more visually appealing and readable. It is a good practice to break up long blocks of text with some sort of contrast. Use titles, lists or notes to create contrast and emphasize important informations, and always use concrete language.
  Markup
    Rules or Suggestions: People read technical documentation differently than they do other types of writing. They tend to skim through documentation to quickly find the information they need. This means good technical documentation needs to have a lot of structured markup to emphasize content and point the reader directly to information they need for the specific subject. Also, use a variety of structural elements to emphasize and break up blocks of content.
  Sections
    Rules or Suggestions: Use sections to separate multiple subjects in the same topic, to create breaks in long blocks of text, and to introduce procedures. The basic idea of using sections is to allow users to quickly find the specific part of the topic that contains the information they are looking for, without needing to read other content that may not be relevant to their specific need. Each section should contain a good title that describes the content of that section. This will also help readers find specific information more quickly.
  Short Sentences and Paragraphs
    Rules or Suggestions: You should try to keep sentences short because they are easier to read and understand. Each sentence should have one basic thought. More than that creates complexity and invites confusion. Likewise, paragraphs should also as short as possible because our brains take in information better when it is broken into small chunks. Also, all the sentences in each paragraph should be interconnected to a single idea.
  Teach
    Rules or Suggestions: Good technical documentation should be focused on teaching or guiding the audience, rather than simply providing arbitrary information. The purpose of technical documentation is to teach a new user to become of expert and then support them once they are.
  Use Structure for Procedural or Task-Related Information
    Rules or Suggestions: Do not bury task-related information within dense paragraphs. This will make your readers very frustrated when they are trying to learn how to do a specific task. Use structured components to make your instructions more visible and appealing. Follow the subsequent guidelines whenever documenting procedures.
    Guidelines for documenting procedures:
    - It is helpful to use titles for procedures, especially when the procedure is surrounded by a large amount of content. This helps the reader to quickly find the procedure that they are looking for amongst blocks of other content.
    - Only use unordered lists (`ul`) when steps do not need to occur in sequence.
    - Always use ordered lists (`ol`) when the steps must occur in a sequence and make sure the items are in proper order.
    - Each step in a procedure should be an action in the sequence.
    - If possible, eliminate steps that lack action. Instead, put informational content after the action within a step, or put it outside the step (for example, in a `paragraph` or `step result`).
    - Use sub-steps rather than putting too many tasks within one step.
    - Clearly identify optional steps. For example, put the word "optional" in parentheses at the beginning of the step.
    - Identify conditional steps with words such as "if" and "then".
    - Use an additional list within a list for branching steps, such as alternative methods.
    - Edit and rewrite ambiguous steps. Proofread the entire procedure, or better yet, have someone else read the procedure, and if there is any ambiguity in any of the steps, the procedure needs to be revised.