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

Add your quality evaluation requirement to the list.

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