Comments on: Documentation Suggestions ??

By: Finishing the last few courses of a geek buffet « Chris Cyvas

Finishing the last few courses of a geek buffet « Chris Cyvas — Mon, 05 Jan 2009 13:00:43 +0000

[...] i installed Ruby and Rails because I was intimidated into doing it [...]

By: chriscyvas

chriscyvas — Tue, 23 Dec 2008 15:07:30 +0000

Thanks a lot Ivan and JD – all good stuff and insightful. Thanks again! Keep up the great work at Mindscape

By: Ivan Towlson

Ivan Towlson — Tue, 23 Dec 2008 05:48:16 +0000

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.

By: Ivan Towlson

Ivan Towlson — Tue, 23 Dec 2008 05:35:43 +0000

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.

By: chriscyvas

chriscyvas — Thu, 18 Dec 2008 22:23:09 +0000

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.

By: John-Daniel

John-Daniel — Thu, 18 Dec 2008 20:41:56 +0000

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