This is a community-driven wish list for attributes that make content valuable, quality content. These are collected through discussions with customers, professional, writers, and personal experiences.

Add your wish to the list.

I wish that content...
  • Solves 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
  • The solution/content presentation is an enjoyable/fun experience - and conversely, is not tedious, dense, or "abstract"
  • 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
  • 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
  • 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.
  • 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.
  • Quality technical writing should be easy to read. One measure of readability is the Gunning Fog Index.
  • 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.
  • 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:
  1. Stop and then restart any resource manager service that participates in the distributed transaction, such as Microsoft SQL Server.
  2. Stop and then restart any resource manager service such as Microsoft SQL Server that participates in the distributed transaction.
  • Avoid incomplete sentences.
    • Keep sentences short. End sentences at the first logical opportunity.  Example:
  1. 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.
  2. 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.