This thread looks to be a little on the old side and therefore may no longer be relevant. Please see if there is a newer thread on the subject and ensure you're using the most recent build of any software if your question regards a particular product.
This thread has been locked and is no longer accepting new posts, if you have a question regarding this topic please email us at support@mindscape.co.nz
|
How do you guys write, maintain, and publish your documentation? It's a really nice format, and a better-than-many interface on the website. I'm getting involved in a couple of open-source projects from the documentation end, and, well, you're inspiring me.
Is it based on documentation generated from inline Visual Studio XML-documentation? How do you go about getting developers to maintain that? Does it get in the way of the code? Do you use any addins (like GhostDoc) to get you started when writing a new thing? Checkin policies & warnings-as-errors?
How do you generate the website-based published-form from whatever you use? How does it get reviewed? I particularly like the fact that the table of contents lazy-loads, rather than the whole tree at once.
If it's based on the VS-XML, can you point me at resources to read to learn more about that? I have a passing familiarity, but summary, parameter, exception and cref is about the limit of my knowledge at the moment. I'm particularly interested in knowing how to add pages like your getting-started section - things that come not from directly inline XML comments, but are of more general scope.
Thanks in advance!
|
|
|
Hi Petemounce, Thanks for your enquiry and thank you for the positive feedback on your thoughts about our documentation! I thought it was a great question that might be valuable to other developers and have written about our documentation process on our blog here: http://www.mindscape.co.nz/blog/index.php/2008/11/19/documentation-the-mindscape-way/ To answer a few things not covered in the post:
If you're particularly interested in attractive web documentation please check out DocProject. I've done some passing investigation into this project because it creates *amazing* web help documentation however at the time it had limitations around including your own generic html help pages which is something we relied on (I enquired and it was possible but somewhat of a hack to get it in there - I was told however that this was changing :-) I hope that helps, John-Daniel Trask |
|
|
Hi John-Daniel
Thanks very much for your detailed reply!
I wonder if you might like to share a couple of sections of the "raw" documentation, and maybe the pertinent bits of the build script/infra? At the moment, the Castle Project team is talking about how best to go about documenting Windsor IoC and MonoRail et al; it would be great for it to be possible for them to see what is possible via Sandcastle and the ancillary tools.
I've looked around DocProject and will try out both that and the Sandcastle Help File Builder over the weekend, I think, assuming nothing goes horribly wrong in the meantime :-)
Best regards
Pete
|
|
|
I'm not really sure why, but when I post, the formatting is lost. I'm using Safari 3.2 on my Mac.
|
|
|
Hi Pete, The "raw" documentation is basically just XML doc comments, as emitted into an XML documentation file by the C# compiler, plus WebGen input. You'll be familiar with the former; as for the latter, it's basically Textile syntax, so it might look something like this (from the LightSpeed QuickStart walkthrough): *Creating the Contribution Class* The <see> element will be resolved by Sandcastle; the sccode markup is a WebGen plug-in that WebGen converts into a <code> element, which again gets resolved by Sandcastle during the build phase. Our WebGen source is a file per topic, organised in the exact same folder structure you see in the compiled help file. This is important because the folder structure is how SHFB knows how to lay out the additional pages. The Sandcastle stuff is all handled via SHFB, which allows us to set it up in a GUI. We just point SHFB at the XML file or files for the API docs. The rest of the documentation -- the WebGen output -- gets brought in via the Additional Content field. We set this to include ..\WebGen\output\*.* and it brings in the folder structure recursively. (We have to exclude the .svn directories created by Subversion, but again you can do that via the Additional Content dialog.) As for the build script, it's just a batch file which calls WebGen and then the command-line version of SHFB: @echo off (That long line should all be on one line.) That should give you a bit more of an idea of what the "raw" stuff looks like and how the various bits fit together. It's not really terribly useful to publish the WebGen source files or the SHFB files because they kinda depend on the LightSpeed source tree and build outputs, but I hope this is enough to point you in the right direction. |
|