One of the practical considerations in designing a xml-based documentation system is creating an appropriate schema.

I'm going to digress here a little, so please bear with me. In theory at least, the users of the system (programmer/writers, editors, other contributors) should never really have to deal with the raw xml - there should be some nice wysiwyg authoring tool they can use to edit documents. There are plenty of off the shelf xml editing tools out there that can be employed by users of the system, but none of them are truly wysiwyg. They can approximate what the output will look like, but the only way for someone using a very complex and data-driven transform system such as ours to accurately 'preview' what a document will look like when built is to actually pump that xml document through the transform tool. Again, it's not really practical for individual users to set up an extremely proprietary and fairly complex build system on their desktops just to see what a document will look like. There is also the problem of staying “in sync” with the binaries and XSLT.

My team solved this problem by hosting the Red October system behind an asp.net web service. Each of the xml documents contains a processing directive that points to an xslt file they keep on their local machine. The xslt is very simple - it uses jscript to instantiate the xmlhttp object in msxml4, passes the xml in the document as a string to the web service using HTTP POST, and the response string is what's handed back to the parser and displayed.

While the programmer/writers that use the system might disagree, I think this is a good way to do it. The problem the users of the 'preview web service' have with it is that I haven't been able to spend as much time as is necessary to maintain it properly so sometimes it goes down unexpectedly or potentially has BUGS in it. Shock, I know. I decided a while ago that that best way for me to spend my time efficiently on it was for it to only run 'release' versions of the Red October bits. It really is a novel use of the .Net Frameworks and asp.net and speaks volumes of the power of said technologies.

I still haven't talked about the actual xml schema yet, have I?