Mailing-List: contact dev-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Apache Directory Developers List" <dev@directory.apache.org>
Received-SPF: pass (nike.apache.org: domain of pajbam@gmail.com designates
 74.125.82.44 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=sender:content-type:mime-version:subject:from:in-reply-to:date
         :content-transfer-encoding:message-id:references:to:x-mailer;
        b=yH7I8xe75JhL4ikFc/3hUkzZ40sZ2CQYuUcPUr9RH6Rp81wJa3HQ9NuPO3GFua6O5y
         aDN8o/8uppOhOcBELGdtUMczb3rzKyKPphN4I9LhsFTyAV8JXbmo+XSQxmvDOVB2QRZQ
         JiTieW1kBvrdBY1Pz2OHl4riUx+Ql8Jbodw2A=
Sender: Pierre-Arnaud Marcelot <pajbam@gmail.com>
Content-Type: text/plain; charset=iso-8859-1
Mime-Version: 1.0 (Apple Message framework v1081)
Subject: Re: ApacheDS Manuals releasing
From: Pierre-Arnaud Marcelot <pa@marcelot.net>
In-Reply-To: <4C7CC05C.60906@labeo.de>
Date: Mon, 6 Sep 2010 13:21:35 +0200
Content-Transfer-Encoding: quoted-printable
Message-Id: <0D96F633-A524-4F76-865A-7989A7C6C366@marcelot.net>
References: <4C7CB61E.9020905@otego.com> <4C7CC05C.60906@labeo.de>
To: "Apache Directory Developers List" <dev@directory.apache.org>

Hi Stefan,

On 31 ao=FBt 2010, at 10:42, Stefan Zoerner wrote:

> Hi Felix!
>=20
> 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/directory.apache.org/apacheds/manuals for =
snapshot
>> deployment as well as for release deployment in a subdirectory
>> *-user-guide-{version}.
>=20
> Are the guides created by docbook already deployed? The URL
> http://directory.apache.org/apacheds/manuals/
> is empty ...
>=20
>> 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?
>=20
> =46rom 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!

Regards,
Pierre-Arnaud=