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 [EMAIL PROTECTED] 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
