--- Chase <[EMAIL PROTECTED]> wrote: > By making the content of the documentation external > to the documentation it causes several problems.
It also solves several problems. It's a matter of which are more important at which time. Putting raw source code in the documentation is different nightmare, and I'd rather have the one we have now than the one we'd have if we did that. With snippets we have the benefit of the compiler and unit tests and (assuming everything is set up properly, which seems an issue at the moment) the sample code/etc. will always be correct. The issue with versioning has been an ongoing issue, since it's not always just a matter of putting "Since S2.1" after a feature: entire snippets may only be valid for an S2 revision. In cases where there are large changes personally I'd set up different snippet prefixes, but either way, it's a pain. Also, with snippets, because it's declarative, more can be done to identify problem code: without snippets (just embedded code) it's more difficult to track down all the code on the site, make sure it's up to date, etc. > The theory behind the snippet macro is to implement the ideas for > LiterateProgramming (http://c2.com/cgi/wiki?LiterateProgramming). > Which states: "Note that documentation means a description of the > implementation, /not/ a user manual.". Javadoc already does this! Javadoc isn't a user manual, it's a reference manual. It can be *used* as a user manual, but it's not a particularly good environment for doing so, and lacks most of the features necessary for use as a general-purpose documentation tool. (That doesn't necessarily mean that the solution as currently implemented is optimal, but it beats writing documentation in Javadoc.) > Real single sourcing would be using docbook to generate a website and > a pdf, not what is being done with the snippet macro. We'd still have some of the same problems. We'd fix some, and add some different ones. > From the point of view of someone functioning in the role > of a documentation maintainer what would the benefit of > the snippet macro be? The same benefit it has now: the code and configuration examples work, because they're functional, tested code. The anti-benefit is that version-specific documentation is updated as the work is done, not necessarily as the wiki is exported, so some exported versions won't match the codebase. Dave --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
