JD and I have had a mail thread going for what is the right level of detail in a guideline. It started as a formatting question – how many levels of heading/sub-heading should we allow and then moved to a more general discussion of guidance scope and granularity.

Here is what we hit upon:

Target of a guideline is the intermediate user. An intermediate level reader should be able to use the guidline to accomplish the task with no need for additional information or steps. This means that novices may get stuck from time to time. You’ll feel this when you start getting the sense that more background is needed or more explanation of steps is required. If a How To already exists for the topic, then great you can use it. However, if nothing yet exists you can now add content to the wiki, link to it from your guidance and keep the guideline tight and clean.

You’ll see the new How Tos link here - http://channel9.msdn.com/wiki/default.aspx/GuidanceLibrary.HomePage. If you need to create a new one then just add a link to this page http://channel9.msdn.com/wiki/default.aspx/GuidanceLibrary.HowTos and write your information.

Practically speaking here are some formatting guidelines that resulted:

1. Never bold your numbered steps within sections. We use numbered steps frequently in the How section and they are often bolded. Go through your items and remove this bold
2. If you feel the need to add subheadings within an existing section or especially within numbered steps you are probably adding too much detail. Look into writing a quick how to (or linking to existing) and pull it from the guideline.