•
•
•
•
Head over to the Team System User Education blog to get a look at a sample of what David Chesnut is calling scenario topics (from an earlier post: Team System User Education on Scenario Topics), and be sure to give him some feedback with your thoughts.
Sample Help File for Scenario Topics
If you have trouble viewing the CHM file, see: Viewing Downloaded CHM Files.
1341
Take a look at a proposal (Visual Studio Team System User Education : Scenario Topics) from David Chesnut of the Team System User Education Team that looks to replace the current orientation-style topics found in the product documentation with something a bit more useful. As always, your feedback is crucial and greatly appreciated.
To me, scenarios represent something fundamental. Documentation should map technology (e.g. work item lists) into the problem space the user is working in (e.g. to track project progress). These serve the same purpose as an abstract in a lengthy technical document: Telling the reader succinctly the key points of the content section so they can decide if they need to read any further.
Source: Visual Studio Team System User Education : Scenario Topics
1315
I was tickled to see that some Team System documentation made it on to The Daily WTF today (not SQL Server 2005 docs as noted in the post), and I'm happy to report that nobody was murdered while writing them. Susan (we don't have a Mark on the Team System doc team) fixed the error and we'll have the corrected page published next week as part of the larger doc refresh for February.
Poor old Mark. Good guy. Kept to himself. Showed up day in, day out, writing documentation for SQL Server 2005 until one day when Sterling L. broke into his office, bludgeoned him to death with his own keyboard, and disappeared. Mark was committed to his company, though, and in his dying moments barely managed to finish typing "Service Pack 1 as part of the installation."
Source: Unsolved Murder - The Daily WTF
1254
When J.D. Meier showed me early releases of Guidance Explorer, one of the things I found interesting was his developer mindset to apply test cases to content development. Today, he wrote up a post about it (J.D. Meier's Blog : Test-Driven Guidance).
If you're an author or a reviewer, this technique may help you. You can create explicit test-cases for the content. Simply put, these are the "tests for success" for a given piece of content.
Just as any good developer internalizes some fundamental tests when creating code, I think many professional writers do the same. However, when you have multiple writers working on a common documentation set, I think it would prove useful to establish tests to ensure that similar documentation from multiple authors satisfy a common set of content tests.
1187
You may recall a release in July of the first Sandcastle CTP (Sandcastle - Documenting Managed Class Libraries). A couple of days ago, we released an August CTP, which you can download here: Sandcastle August CTP Download.
For a full list of new features, and a list of bug fixes, see: Sandcastle August CTP Release Notes.
1051
Tags: sandcastle
If you've always wanted to create MSDN-like documentation for your managed class libraries, you'll want to take a look at a project called Sandcastle. For an overview of this project, see Sandcastle Overview, which includes an attached PowerPoint presentation about it. The first CTP is now available (Announcing Sandcastle CTP) and you can find instructions on building a CHM here: Creating a CHM build using Sandcastle. To keep current on this project, be sure to follow this blog: Sandcastle.
1001
