Went to a East Bay .NET user group meeting tonight, ‘specially, because David Wright, architect of the Sandcastle team was speaking.
I’ve seen David’s presentations on various videos, but it was a delight to meet him in person and see the passion that he brings to the special arts that involve bringing automated tools into the world of documentation. This is a subject that is very dear to my heart.
I have to say I almost deleted the word “passion” in the last paragraph. MS have really devalued it. But I mean it, it’s the right word, and… I won’t let it be taken away from me by a bunch of marketeers.
Another thing that is dear to my heart and that I believe I have mentioned before is Sandcastle’s validation of XSLT as a robust means of supporting multiple types of content generated in a pipeline.
Anyway, XSLT or no XSLT, I went to this presentation because I hope to get RDLDocumenter to slip Reporting Services metadata directly into application docs, as a first-class citizen. I am still casting around for exactly the right/best place to finesse XMLRSDocs into the Sandcastle pipeline, but I sure got a lot of ideas tonight, and if one chooses to bring XSLT into the equation, Sandcastle makes that choice a no-brainer. I had fun.
Still, I’m saddened. David believes passionately in the value of automating documentation, and so do I. But he thinks that the problem with the quality of the content his tool is generating is the number of User Ed folks it would take to keep up with the mushrooming number of API topics that need to be documented. He also thinks that dev folks can’t, or won’t, write good documentation. Here, we differ.
If David were right about whether or not devs can, or will, write good docs, the truly valuable documentation on the new .NET framework features would not be in the dev blogs. And that’s where it all is these days.
Programmers and PMs are writing extensive, informative, meticulously formatted and beautifully expressive blogs, replete with really useful code samples and conceptual background… because (pick one, pick all):
- they’re desperate for their work to be understood and properly used
- they haven’t a hope in hell of getting it properly exposed otherwise
- they’re proud of what they’ve done
- they’re the best and closest authority on what they’ve done
- they’re encouraged in-house to spend their (ahem) “free” time stepping up to the plate to fill this gap
- … ? Your call.
I don’t know exactly why they’re doing it, but they sure are doing it, so I know they can and will.
What am I saying “they” for!?! TMM is basically the same deal. I’m in the same trap.