james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Danny Angus <Danny_An...@slc.co.uk>
Subject RE: site process
Date Thu, 16 Dec 2004 09:17:58 GMT
Steve,

> I would not
> like to see us using one build tool for the website and docs. and another
> for the source. This would just be confusing and cause extra work.

This is a fair point, and one I knew would come up.
I don't have the answer to this one, except to say that it may be less
impractical if the source tool doesn't change, and continues to produce the
product documentation for inclusion in distributions, but web-site tool
does; requiring only those who want to build the whole site (as opposed to
the product docs) to get to grips with a new technology.

>Speaking of extra work, changing to another base document format would
>require that all of the existing documents be changed. In my view, we
would
>need some very compelling advantages to undertake this work, and ideally a
>tool that performed the transformations for us.

I wouldn't propose that we did this, not unless we could use a real simple
once-only single step migration, like a single xsl transformation.
Bear in mind that Maven can manage the existing xdocs format requiring only
that we re-do (transform) the navigation.

> Regardless of format and tools, we do need to change the directory
> structure. I am not sure we need to do more right now. What problems do
you
> envisage a change of tools or format solving?

None specifically, but there are three points to consider.

1/ we ought to look at separating site docs from project documentation as
they exhibit different lifecycles.
In fact this is why we have the site-dev@james list and we always planned
to have a site module.
2/ for sanity we need to have a single document format from which we can
generate documentation & web-site for a number of alternative destinations.
3/ Ant performing xslt is not a multiproject documentation tool, but has a
number of benefits, simplicity and familiarity being chief amongst them.
OTOH I'm currently using Maven at work for building multi-project
documentation and reports, and we're using cruisecontrol to make regular
documentation "drops" and after the initial set-up the documentation task
becomes; edit-an-xdoc->commit. The checkout, build and publish are all
taken care of by the machine. We can cope with multiple versioned sets of
docs, i.e. having the sets for every release of every module all available
on the site. And we've integrated the reports which Maven can manage
checkstyle, pmd, junit.

I'm just not sure what appetite we have for radical reform of process as
well as of structure.

d.


***************************************************************************
The information in this e-mail is confidential and for use by the addressee(s) only. If you
are not the intended recipient (or responsible for delivery of the message to the intended
recipient) please notify us immediately on 0141 306 2050 and delete the message from your
computer. You may not copy or forward it or use or disclose its contents to any other person.
As Internet communications are capable of data corruption Student Loans Company Limited does
not accept any  responsibility for changes made to this message after it was sent. For this
reason it may be inappropriate to rely on advice or opinions contained in an e-mail without
obtaining written confirmation of it. Neither Student Loans Company Limited or the sender
accepts any liability or responsibility for viruses as it is your responsibility to scan attachments
(if any). Opinions and views expressed in this e-mail are those of the sender and may not
reflect the opinions and views of The Student Loans Company Limited.

This footnote also confirms that this email message has been swept for the presence of computer
viruses.

**************************************************************************

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message