These are collected through discussions with customers, professional, writers, and personal experiences.

Add your quality evaluation requirement to the list.

Table of Contents

Quality Wiki content must...

Be related to Microsoft Technology

  • The Wiki has a strict requirement to relate to Microsoft based technologies


Be Focused, on-topic


Have added value

  • Solve the customer's problem
    • Does the content solve a problem that can easily be solved by 90+% of our users; if so, does the time that content takes to create take away from the hard problems that 90%+ find it difficult to solve on their own
    • Reduces time to solve the problem or implementing the solution
    • Reduce the cost of solving the problem or implementing the solution
    • Improves the overall quality of the solution in various realms, which include, but are not limited to: security, performance, interoperability
  •  Don't simply post the bare technical details, provide detailed explanation and background. Guide the reader through the script with comments

Be community based (non-personal)

 

Have structure

  • Good technical content should be both transparent and self-declarative.
    • If it applies to version X but not Y, it should say so prominently at the top.
    • If it has prereqs (including admin permissions) it should say so each and every time it is relevant.
    • If following the recommendations has potential negative or unintended consequences - alert the reader to them.
  • Does the content “connect the dots”? A lot of content (not just ours) provides a box of dots and leaves it up to the reader to connect them
  • Does the content provide a mechanism for the consumer of that content to “validate understanding”? This could be done with examples, graphics, questions/answers, video demonstrations, Test Lab Guides, etc.

 

Be complete

  • Content is complete - avoid paper or "link" chases - put required information inline if at all possible
  • Content answers a question
    • ask yourself "what questions does this content answer
    • if you conclude that it answers no questions, ask someone else if they can think of questions that it answers.
    • If the only questions you can think of are questions that customers are unlikely to ask, then maybe we don't need that content, or the content needs to be reworked
  • Avoid incomplete sentences.
    • Keep sentences short.
    • End sentences at the first logical opportunity. For example:
      • To resolve this problem, you must remove user information from two database tables, and then reset Microsoft Internet Information Services (IIS) on the RMS server.
      • To resolve this problem, you must remove user information from two database tables. Then, reset Microsoft Internet Information Services (IIS) on the RMS server.
    • Example two is easier to machine translate.

 

Be logical

  • Content designed to implement a scenario, behavior or feature should provide for validation testing so that the reader can confirm if the guidance is followed, the intended results will result.

 

Be readable

  • Quality technical writing should be easy to read. One measure of readability is the Gunning Fog Index.
  • The solution/content presentation is an enjoyable/fun experience - and conversely, is not tedious, dense, or "abstract"

 

Be Consistent

  • Are there at least two examples to supplement abstract concepts or concepts that are newly introduced which would be very difficult to other understand without them?
    • Graphics add value. Good examples are screenshots architectural diagrams and workflow diagrams. They should illustrate the text and use the same terms. A good example is the Acitve Directory Components poster.
    • Script samples add value. They should be based on the real-world problems not "hello world"
    • Is there a Test Lab Guide that shows them how to configure the steps? There is no replacement for hands-on experience to add meaning to abstract concepts
  • Content that is easily machine translatable (MT) will be easier to translate, and therefore potentially reach a larger number of IT Pros. To make MT easier:
    • Avoid Title-style capitalization. MT translates capitalized words inside sentences as nouns. 
    • Avoid text in parentheses that does not relate to a concept that the text is near.
    • Keep phrases next to words they modify.  Example: "
      • "Stop and then restart any resource manager service that participates in the distributed transaction, such as Microsoft SQL Server."
      • "Stop and then restart any resource manager service such as Microsoft SQL Server that participates in the distributed transaction. "

Respect the rules

 

See also