Using MAML for conceptual documentation of library

Question

I am working on a new library and I am using XML comments for API documentation along with SandCastle which works really well.

But I need to write additional documentation which covers concepts, overall architecture, working demos etc, class diagrams etc.

I have 2 options:

1. Use some wiki engine and write documentation wiki style.
2. Use MAML which seems to be for this purpose.

Using wiki seems safe solution because there are many stable, popular and free engines available but API and conceptual documentation will not go hand in hand (cross-linking, appearance etc). Using MAML means a learning curve and I am not sure about how mature it is and what are its advantages/disadvantages.

Have you used MAML/Wiki for this purpose and what have been your learnings? What would you suggest me?

Answer 1

Personally, I love the freedom of working w/ a Wiki. At this point, you have a few decent choices for editing MAML

• DocProject
• Sandcastle Help File Builder

I can't speak much to DocProject (though it looks nice). Right now, I'm using SHFB to merge API documentation and some conceptual docs into MAML. The editor is decent and more than suffices for my needs. I'm able to easily set up a table of contents and link between my API and conceptual documents. A good resource to look at for examples is SandcastleStyles.

As with all things, there are some important questions to ask.

• Do you have any requirements to ship your documentation in one package? In my case, I needed to ship everything in one nice compiled package. You can't do that w/ a Wiki, but you can do that w/ Sandcastle.
• Are you going to be the only person updating the conceptual content? Most wikis have a really nice editor and an ability to quickly link between topics. The only tool you need to edit content is a browser, which might be a requirement for a less technically-savvy writer.