directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pierre-Arnaud Marcelot>
Subject Re: ApacheDS Manuals releasing
Date Mon, 06 Sep 2010 11:21:35 GMT
Hi Stefan,

On 31 août 2010, at 10:42, Stefan Zoerner wrote:

> Hi Felix!
> Felix Knecht wrote:
>> I just wonder what of the manual shall be release to where.
>> Do we need to create a zip file of all the generated docs and release it
>> as artifact like releasing a jar file? ATM the generated docs are
>> deployed to p.a.o/www/ for snapshot
>> deployment as well as for release deployment in a subdirectory
>> *-user-guide-{version}.
> Are the guides created by docbook already deployed? The URL
> is empty ...
>> Do we need to deploy a released source zip of all?
>> Do we need to deploy a release pom.xml (ATM the module is
>> <packaging>pom</packaging>?
>> I'm even don't know if it's possible to release and deploy a zip.
>> Any thoughts?
> From my point it would be interesting to have the manuals (guides) be part of the ApacheDS
release itself. PDF versions should be sufficient. No need to have the html in the download.

I was first tempted to have two separate repos, one for the server and another for its documentation.
It had the advantage to be able to release both independently...
... But, in the end, and from a user point of view, I think you're right and the documentation
should actually be part of the release.
It will be a lot more work and will probably take a little more time, but in the end, the
user experience is way better.
Having an up-to-date documentation alongside the server is really a must have for our users.
Furthermore, as the release is dependent on the documentation, it will force us to update
the documentation, something we've not been quite good at since a few last releases (and the
documentation becoming release after release less accurate).

However, I'd rather encourage the use of the HTML version when bundling the documentation
in the release packages. The main reason for this is that it does not require an additional
installation of a PDF Reader software (Mac OS X and Linux comes with a built-in reader, but
Windows doesn't and more than 2/3 of our users are on Windows).

> I have started to rework the Basic User's Guide for the 1.5.7 version of ApacheDS. This
task looks meaningful to me since editing takes place in svn, and the efforts are therefore
more durable. It will take some time, but I hope a presentable version will be available in
some weeks.

Thanks Stefan!

View raw message