+1 for Confluence approach. Readable guide even with minor inconsistencies between versions is more important to users than the *potential* for version exactness. The great danger is that the version-specific docs still won't be kept up-to-date in which case its worse than the Confluence approach. Javadocs is the ultimate reference documentation for a particular version - no need to duplicate what's in the Javadocs.
Kalle On Thu, Jul 1, 2010 at 1:49 AM, Ulrich Stärk <[email protected]> wrote: > I think the choice we have to make is whether we want to make the > documentation easy to maintain and set the barrier for potential > contributors as low as possible, at the same time making it a bit harder for > users to get documentation for their specific version (Confluence approach) > or whether we want to give users documentation for their specific version > where we can also keep the documentation for older versions updated, at the > same time making it a bit harder for the authors (svn + some documentation > build tool). > > On 30.06.2010 18:45, Piero Sartini wrote: >> >> This could work using the "Copy Space Plugin". >> >> https://studio.plugins.atlassian.com/wiki/display/CPSP/Confluence+Copy+Space+Plugin >> >> We would end up with different spaces: >> TAP5 could be the trunk, >> TAP51, TAP52, etc the snapshots. >> >> Piero >> >> 2010/6/30 Howard Lewis Ship<[email protected]>: >>> >>> What about a way to snapshot the current documentation? So we could >>> snapshot the current state as "5.1", then start updating it. When 5.2 >>> goes final we could snapshot that as "5.2". I.e., tree it a bit like >>> SVN, but inside Confluence. >>> >>> On Wed, Jun 30, 2010 at 5:38 AM, Ulrich Stärk<[email protected]> wrote: >>>> >>>> This is just to keep you up-to-date to what I'm doing. Ideas and >>>> suggestions >>>> are most welcome. >>>> >>>> I've finished porting the 5.1 reference documentation and the cookbok to >>>> confluence. This was a matter of using a doxia converter and some >>>> additional >>>> regexps to clean up things. Importing the stuff into confluence had to >>>> be >>>> done manually though. >>>> >>>> I'm now investigating how to keep the documentation in sync with our >>>> releases so that people interested in the current documentation, the >>>> documentation for a specific version and people interested in the >>>> differences between two versions all find what they need. My initial >>>> idea >>>> was that we could do with some macros that mark parts of the >>>> documentation >>>> as deprecated or add a "since" information to it. I fear that this will >>>> make >>>> the documentation unreadable though as features are added, changed and >>>> removed. People looking for documentation on a specific version will >>>> have to >>>> ignore the parts talking about deprecation or addition of features not >>>> applicable to their version of the product. Or we have to support that >>>> by >>>> hiding the unnecessary information by means of javascript or something. >>>> All >>>> that is cumbersome to the reader though. >>>> >>>> An easier approach would be to not put the reference documentation into >>>> confluence but maintain it in svn where it would live the same lifecycle >>>> as >>>> the product itself. This will make it a bit harder to maintain for the >>>> documentation authors though. >>>> >>>> Right now I am favouring the second approach where we put the reference >>>> documentation (i.e. the user guide) into svn and have tutorials and >>>> cookbook >>>> articles in confluence. I will work on that in the next days. >>>> >>>> Cheers, >>>> >>>> Uli >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: [email protected] >> For additional commands, e-mail: [email protected] >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
