MAML is my new best friend!

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…

Posted in Best-practices, Uncategorized
2 comments on “MAML is my new best friend!
  1. Mike says:

    It seems that you never have written these posts about “Conceptual content”? I’m just looking for a “how to” …

    Like

  2. Rob Seder says:

    @Mike – download Sandcastle from Microsoft (here: http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=10526), then download Sandcastle Help File Builder (here: http://shfb.codeplex.com/). Once you have those, using SHFB, you can add this conceptual content. They have a whole section on it, with templates and everything. Let me know if you get stuck of have questions, I hope that helps.

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Archives
Categories

Enter your email address to follow this blog and receive notifications of new posts by email.

Join 4 other followers

%d bloggers like this: