So, as discussed – Jamie and I have been working on this urgent/critical project. We delivered 1.0 this past Friday. We have been doing XML code comments all along, and intended to just use Sandcastle and SHFB to generate the component documentation. However, for some reason – I was wandering around the “Conceptual Content” area with SHFB. I never really got how to use this and didn’t really understand what it was. However, for some reason – it clicked this time around.
Conceptual content is the notion of having regular “documentation” in your .chm or website that you generate using Sandcastle. Now, SHFB uses the Html Help Compiler and Sandcastle, which support MAML, or Microsoft Assistance Markup Language. This is a markup language that was designed to create structured documentation. That is, imagine just storing your documentation within XML tags and instead of doing any formatting, you would rely on the whatever is being used to render the content?
Supposedly, this is how all the content on MSDN is written – and the concept does make sense: you write all of your content within XML tags, and leave it to the renderer to determine how it actually looks.
I plan to do some other blog posts on the details of this in the future. This is pretty heavy semester for me at school, but I’m still trying to get a blog post out around once a week if I can. I still have a lot of content queued up, just not enough time to actually write it up. Anyhow, more to come…