There are some things that I WANT desperately to get right before we start on dC v.Next and one of those is documentation. I am talking about conceptual, code examples and and API documentation. The API documentation is pretty well taken care of with some xml comments and some discipline, but the code examples and conceptual stuff is not so easy to get in there as part of the development process.
Ideally, the build process will spit out the documentation – all of it into one help package. The guys as Mindscape have briefly documented their documentation process, which I may use, but I was hoping to avoid the Ruby stuff.
I found the DocProject project, but it’s still a very manual process.
Does anyone out there have any good processes in place to take care of this? Are there any OSS or commercial applications that make this easy?
December 18, 2008 at 3:41 pm
Just out of interest – why avoid Ruby?
Unlike some things it’s not like it chews resources when not in use and it’s pretty simple to get setup with.
I’m not saying this to be a pain – I completely agree that the documentation process is too cumbersome as it stands with existing tools – but more seeking additional information as to why you’d like to avoid Ruby.
Cheers,
– JD
December 18, 2008 at 5:23 pm
Because I’m a wussy
Nothing against Ruby – I’ve just always tried to keep my enviroments pretty “clean” for lack of a better term, as I have a few boxes to maintain and an install on one is an install on another.
But, you have humiliated me into downloading and installing Ruby and Rails and all the other stuff.
December 23, 2008 at 12:35 am
Hi Chris,
Just to be clear, the only part Ruby and webgen play in the Mindscape process is allowing us to write our non-API documentation using Textile markup rather than HTML. (We’re wussies too.) So if you want to avoid the Ruby dependency, you could either write the additional pages in your HTML editor of choice, or use some other preprocessor with fewer or more acceptable dependencies.
Everything else is handled by Sandcastle Help File Builder. SHFB has a facility for including external HTML files, however generated, which makes it easy to bring in conceptual and task-oriented pages alongside the XML API docs. And it is SHFB, not webgen, which imports and formats referenced code fragments, so if you want to avoid dependencies you can still pull in code examples just by handcrafting the
tags. (Mostly. For our WPF products, we also need to import XAML fragments, which SHFB doesn't automate, so in this particular case we do it at the webgen level.) There are a couple of things you need to watch out for around hyperlinking from conceptual pages to XML-generated docs, and these can get a bit fiddly if your API makes significant use of generics (as LightSpeed does), though these can probably be simplified pretty easily if (a) you use an extensible HTML preprocessor such as webgen (which we do) and (b) you get annoyed enough to write the necessary macro (which we haven't, yet).Would be happy to share more info with you if it would be helpful -- drop me a line.
December 23, 2008 at 12:48 am
Yay formatting engines. For the strange lacuna where WordPress decided to paragraph, block-quote and change font in my previous comment, please read “just by handcrafting the left-angle-bracket code right-angle-bracket tags.” I.e. you can import code fragments by reference using SHFB alone, using the ‘code’ tag to which SHFB gives special handling; you don’t need Ruby/webgen for this.
December 23, 2008 at 10:07 am
Thanks a lot Ivan and JD – all good stuff and insightful. Thanks again! Keep up the great work at Mindscape
January 5, 2009 at 8:00 am
[...] i installed Ruby and Rails because I was intimidated into doing it [...]