Very well... What needs to be done now then is to move the documentation for the various submodules
to confluence. Maybe I'll also create a separate space for the documentation, that will make it
easier to give access to contributors that aren't supposed to edit the site itself. I think I'll
begin with that tomorrow.
Another thing that needs to be done quite soon is incoroporating the new logo into the layout and
update the layout so that the documentation looks nice. Robin, can you work on that? I'd also really
appreciate it if you could file a CLA, that will help avoid IP and licensing issues and I can then
grant you access to the new site and documentation so that you can work directly on it.
Cheers,
Uli
On 01.07.2010 19:21, Kalle Korhonen wrote:
+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]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
