MAML, MAML, MAML, MAML

Mar 23, 2008 at 7:13 PM
Hello All.

I'm working on a project that's going to have quite a bit of conceptual-type content -- Developer's Guide, Walkthroughs, Tutorial, etc. I've been looking closely at MAML, sifting through what little info there is on the Web and poring over the Conceptual example in the latest release.

I'd like to air my thoughts so far and hopefully get some feedback to try and make sure that I'm grokking the situation. : )

From what I can tell, MAML is designed (and used internally by Microsoft) as a Help content server, implemented as a XML relational database, relating topic content to language, semantic type (something like 17 schemas?), and parent content. And likewise with associated media content. This content is served upon request in the desired format, either HTML, RTF, XML, or whatever.

Okay, for Microsoft, that makes a ton of sense. Or for any organization with a mountain of content which is frequently needed in varying languages and formats.

So, here's where I may be missing something. For a compiled HTML Help file pertaining to a normal project, be it a class library or application, the language, media, and format are fixed. I don't see the incident benefit in expending the effort to maintain the content in a rigorous MAML structure. Because:

  • As I see it, one of the primary advantages of MAML content is the ability to use the Sandcastle Conceptual transforms to emulate the API documentation; however, creating a custom transform to emulate the API transform is mostly trivial.
  • In the case of localization, both approaches have the common expenditure required to translate and localize the content (text and media). Using MAML, that content then has to be related within the MAML content structure, with the appropriate support files.
  • Even using a WYSIWYG MAML content editor, there would still be a rather large degree of configuration required to establish the structure and to edit its contents. On the other hand, a custom transform to emulate the API documentation generally consumes a much simpler schema, with minimal configuration.

Now, I understand that the potential for MAML, in terms of scalability and flexibility, is far greater. Also, whenever a WYSIWYG content editor is available, that will narrow the gap somewhat. As it stands though, I can't see using MAML simply to be able to use the Sandcastle Conceptual transforms. Sandcastle is so configurable that it's just much simpler to use a custom transform to emulate the API documentation.

That's the situation at present, as I see it. Any thoughts?

Mark
Mar 24, 2008 at 4:39 AM
Hi Mark,

MAML is simply a way to write help topics in terms of structure instead of format; i.e., it will allow you to write help by organizing it into sections and/or user tasks without having to worry about layout and appearance. Then you choose a Sandcastle presentation style such as VS2005, which has XSL transformations and a BuildAssembler configuration file (conceptual.config) specifically for producing conceptual content. Sandcastle will convert your XML-based MAML topics into individual HTML files with the same look and feel as auto-generated reference documentation.

The benefit is that it's much quicker and easier to write help. It's also easier to change formating at any time, throughout your entire documentation set, since you can update the XSL transformations and CSS styles separately from the MAML help topics and then simply rebuild.

Localization can be accomplished in both MAML and auto-generated reference topics using Sandcastle's content item approach, which is basically a simple way of extracting common text so that it can be reused in multiple topics. To have the actual help content localized you need to maintain multiple sets of MAML topics and multiple sets of XML documentation comments, one per language, and then build each set separately. You can use the same presentation style and settings though since the only thing that will change is the help content.

I've already considered creating a WYSIWYG MAML editor for DocProject 2008. There won't be a large degree of configuration required since the MAML schemas are well-defined. I simply need to create an editor for each of the schemas (19, by my count), although I plan to make it as generic as possible in the hopes that it will allow authors to define custom schemas as well.

The reason why using MAML is a better choice is simply because Sandcastle already works with it out-of-the-box. Yes, Sandcastle is flexible enough for you to create a proprietary format, but why bother?

You may want to try DocProject for Visual Studio 2005 since it will compile your MAML content and auto-generated reference documentation into a single documentation set automatically. It may at least give you a better sense of why MAML is a good choice.

- Dave
Mar 24, 2008 at 8:01 PM
Hi Dave,

Thanks for your thoughts. I agree that MAML is a good choice, but I don't think that it is the better choice; not yet, anyhow.

I also think that your per-schema editor idea is a good one, especially if it has an extensible framework model. I presume that the base class for such editors would take care of auto-generating the support files required, like the project MAML manifest, xml companion files, and such. As I say, such an editor suite would go quite a way to narrow the gap.

The other points you mention apply equally as well to the alternative approach. There are other tools extant that will transform and include content in addition to the API documentation; the localization and shared content approach is the same with either approach, although with MAML -- from a tool builder's perspective -- it should be easier to build either a custom build component or configuration editor to allow the developer to build any supported culture version simply by setting a switch.

That, I believe, is MAML's main utility -- as a content server. If one doesn't need the capability that a server provides (i.e., content served based on request) then it doesn't make sense to me to use it, especially given the absence of a capable editor.

As far as working with Sandcastle out-of-the-box, I don't mean a proprietary format, although that is certainly possible. The main_sandcastle transforms for the three doc models only require minimal adjustment to produce output for additional content which mirrors the API documentation.

I'm not saying MAML is a bad idea, just that it's not as good an idea as it could be. (Yeah, name me something that is : ) ) 18 months seems to be a magical time span in the software world; perhaps by then it will be easier to use the MAML approach than not.

As you're considering building an editor, let me mention a few items for consideration. I'm sure you've thought of most of them already.
  • I really like your per-schema extensible model. Good idea.
  • There needs to be an editor to include and relate media resources (relations based on culture and topic, certainly, but perhaps also on content type)
  • The MAML structure and all those GUIDs should be completely abstracted, into a tree view or folder/file presentation or something similar.
  • Cross-linking between content (both API and conceptual) and from content to MSDN should be through human-readable topic URIs and/or point and click.
  • These editors will be used for creative content, and as such, should provide for custom names for the various elements and resolve them to MAML elements behind the scenes.
FWIW, that's my two cents on the editor. I agree that MAML "could" do for content what XSL and CSS have done for presentation. I just don't think its there yet.

Mark
Mar 24, 2008 at 9:34 PM
Hi Mark,


I also think that your per-schema editor idea is a good one, especially if it has an extensible framework model. I presume that the base class for such editors would take care of auto-generating the support files required, like the project MAML manifest, xml companion files, and such. As I say, such an editor suite would go quite a way to narrow the gap.

DocProject already does all of that - generates the MAML manifest, XML companion files and merges the conceptual TOC and the reference TOC, which you can define by simply dragging & dropping topic 'nodes' in a tree view-like control. The purpose of the editor will be to help authors write the MAML topic files using specific features like having design mode and source mode, having the schema structures built-in to the editor and also the different MAML elements could be tool box items. I also plan to create a properties dialog that allows an author to choose options for individual topics that can be written to the XML companion files, which means that these files might actually be pre-generated in the future (when they are needed) instead of being generated during builds, like DocProject does now.


The other points you mention apply equally as well to the alternative approach. There are other tools extant that will transform and include content in addition to the API documentation; the localization and shared content approach is the same with either approach

Except that alternative approaches are proprietary, while MAML is something that, presumably, Microsoft will maintain and update with each Sandcastle release. Also, it's here now and it can accomplish everything that the auto-generated reference build process allows a developer/author to accomplish so I really don't see the benefit of using an alternative solution.


although with MAML - from a tool builder's perspective -- it should be easier to build either a custom build component or configuration editor to allow the developer to build any supported culture version simply by setting a switch.

Unfortunately, that's not always possible due to limitations in Help 1.x (.chm), although if 1.x isn't being used then it shouldn't be a problem, regardless of whether MAML is used or not. MAML doesn't seem to add any restriction on how localization can be accomplished.

I plan to add support for localization in DocProject 2008. Right now topics are stored in each project's Help\Topics folder, so I plan to provide support for sub-folders with locale names, such as Help\Topics\en-US, and the same for external XML documentation files, Help\Comments\en-US and shared content items, such as Help\Presentation\Style\Content\en-US. If DocProject detects these folders it should be able to run the help build process once for each locale folder to build multiple localized documentation sets in a single build. I'll also add a project setting that will allow users to restrict the locales being built and, if necessary, provide additional information about each locale. I don't think that MAML is going to be a bottleneck though.


That, I believe, is MAML's main utility -- as a content server. If one doesn't need the capability that a server provides (i.e., content served based on request) then it doesn't make sense to me to use it, especially given the absence of a capable editor.

I disagree. I believe that MAML's purpose is to quickly and efficiently author help topics without having to worry about format and clutter. But I haven't heard of it being used for serving content (I assume that you mean from a database or web service?). I think that the content in Windows Vista help system was developed in MAML, so obviously it has its use for building compiled help. The benefit of using it with Sandcastle is that Sandcastle already provides first-class support for building conceptual documentation from MAML so that you don't have to use an alternate approach, like raw HTML or a proprietary XML-based help format.


As far as working with Sandcastle out-of-the-box, I don't mean a proprietary format, although that is certainly possible. The main_sandcastle transforms for the three doc models only require minimal adjustment to produce output for additional content which mirrors the API documentation.

I'm not referring to the XML transformations or the build assembler configuration file when I say proprietary format. What I mean is the format of the individual help topics, since we're discussing MAML :) If you don't use MAML then you'll probably use HTML, which in my opinion is not the best choice, or you could create a proprietary XML-based format, but that doesn't make any sense either since MAML is an XML-based format that already works in Sandcastle. And if you're willing to make the updates to the existing transforms to build help using your proprietary format, then I assume that Microsoft will not guarantee that the changes you make will be easy to make in subsequent releases, although I assume that the conceptual transformations will be updated by Microsoft so that's a huge benefit when using MAML - there's already support for it.


I'm not saying MAML is a bad idea, just that it's not as good an idea as it could be. (Yeah, name me something that is : ) ) 18 months seems to be a magical time span in the software world; perhaps by then it will be easier to use the MAML approach than not.

Personally, I don't feel that authoring help in MAML is any more difficult than authoring help in raw HTML. I'd even suggest that it's easier since you use it from an author's perspective, not a web designer's perspective. What makes you think it's so difficult to use?


As you're considering building an editor, let me mention a few items for consideration. I'm sure you've thought of most of them already.

I certainly appreciate the feedback :)


I really like your per-schema extensible model. Good idea.

Thanks, I suspect it will be the most difficult part. It will almost be like a graphical schema editor in some sense.


There needs to be an editor to include and relate media resources (relations based on culture and topic, certainly, but perhaps also on content type)

Agreed. As I mentioned early, I plan to do something like this.

To add a bit more detail, I plan to create a properties dialog for topics that can be invoked from the Topic Explorer. The dialog, I assume, will serialize some of the settings to XML companion files. Currently DocProject lets you choose the type of MAML topic before you write it, but not afterwards. I'll probably keep this behavior. Culture, and globalization in general, is something that I haven't put a lot of thought into yet but I will for DocProject 2008.

For adding images (media) in external XML comments for auto-generated reference documentation, DocProject automatically handles storage and path management if you use DocProject's Topic Editor. I plan to do the same for the conceptual editor.


The MAML structure and all those GUIDs should be completely abstracted, into a tree view or folder/file presentation or something similar.

DocProject's Topic Explorer already does this (screenshot). The dialog in the screenshot encapsulates the Topic Explorer tool window for external use (i.e., outside of Visual Studio). Disregard the dialog's name since it was changed to Topic Management, without the AIP, when I finally introduced first-class support for conceptual documentation although I simply forgot to update the caption. Topic Explorer is the tree view, which supports drag & drop to define the TOC that, as you can see, consists of mixed conceptual and auto-generated reference topics.


Cross-linking between content (both API and conceptual) and from content to MSDN should be through human-readable topic URIs and/or point and click.

Agreed. DocProject currently supports dragging a conceptual or auto-generated reference topic from Topic Explorer into the Topic Editor (which is for authoring external XMl documentation) and it will create an HTML anchor or <see> link automatically. I plan to do the same for the conceptual editor (as a matter of fact, the code already exists for my first attempt at writing the editor a couple of months ago. I didn't succeed though because I tried to stuff MAML into my external XML documentation editor, but the impedance mismatch was just too great).


These editors will be used for creative content, and as such, should provide for custom names for the various elements and resolve them to MAML elements behind the scenes.

That's a good idea, but it won't be required for what I have in mind. I've already drawn up a very lo-fi UI diagram for what I want, and if it's something that I'll actually be able to accomplish, then the MAML editor will not just be a fancy XML editor - it will provide an experience kind of like Visual Studio's HTML editor, but with support for block sections.


FWIW, that's my two cents on the editor. I agree that MAML "could" do for content what XSL and CSS have done for presentation. I just don't think its there yet.

Without an editor, I understand your concern. However, I don't think the alternatives (i.e., updating the existing transformations manually and authoring topics in raw HTML or a proprietary XML-based format) provides any advantage over MAML. And as mentioned previously, I believe that MAML has a few advantages over the alternatives.

- Dave