Sorry for the late reply, this looks good to me for starters. I have
some comments, though :) Maybe we can split this doc set into "1.0"
and "1.x" topics as well (and comment out the stub pages for 1.x
things).
On 07/11/2007, at 1:18 AM, Joakim Erdfelt wrote:
Introduction
* Welcome
This is the index, presumably not needed in the menu
* License
I think this should be under the standard project information
location, and highlighted on the download page (probably not needed
here)
* Download
* Quick Start
Looks good
Users Guide
How about a Feature Overview at the top here that links in to each of
these?
* Browsing
* Searching
+ Find artifact
Keep this menu basically identical to the left menu of Archiva so
that you can have a 1-1 help link in Archiva itself.
* WebDAV Features
I'd drop this
* Using Repository ...
o As a Maven 2 repository
o As a Maven 1 repository
o As an Ivy repository
How do you use it as an ivy repository? Isn't that presently just
using the Maven 2 layer? If so - maybe just link to the Ivy docs for
now.
Do we need a separate one for Ant (using the Maven ant tasks, or
<get />).
* Deploying to Repository
o Using Maven 2
o Using Maven 1
o Using Ant
System Admin Guide
* Structure of Archiva
What goes in here? If I were a sys. admin, I don't know the reason to
read this doc.
* Installing
o Installing Standalone
Installing standalone should be covered in the quick start - but this
can cover advanced things like PLEXUS_BASE
o Installing on Jetty
o Installing on Tomcat
o Installing on Geronimo
I wonder if we just cover one example here (say, Tomcat) - and link
to the wiki for contributions of other servers that have been tested
with? When we move the wiki we can generate that into the site
anyway, but it just means it can be updated between versions.
All these docs should cover upgrading too.
There's missing doc that covers what configuration files are used.
* Databases
o Embedded Derby DB
o External MySQL
o External PostgreSQL
Same comments as for appservers.
* Security
o Roles
o Using LDAP
* Runtime Configuration
o Repositories
o Proxy Connectors
o Network Proxies
o Consumers
I think these (particularly "consumers") would be better in a series
of HOWTO guides:
- how to configure repository purging
- how to configure a proxy
- how to control which artifacts are proxied
- how to configure security for a repository
- ... etc.
We also need a "customising Archiva" section for plugging in your own
consumers as Deng suggested.
* WebDAV Server
what is this?
* Repository Synch
1.x :)
Reference
* FAQ
FAQ isn't really a reference - this should be a wiki link in the end.
But I think we can remove until we have some frequently asked
questions (I don't like having it as the "I don't know where to put
this documentation bucket" :)
* Community
o How to Contribute
o Development Team
o Mailing Lists
o Issue Tracking
o Subversion Repository
Many of these can be in the (admittedly inadequate) default reports -
I'd only add those that we differentiate. I wouldn't put it under
reference.
* Building / Hacking
* Java APIDoc (javadoc)
* Source Cross Reference
* Test Cross Reference
I think all these can be under a developers section instead. Building
is a document of its own, and then we can start breaking out docs
like the dev guide on the wiki - but this can all come later.
Other stuff:
- we want to ensure we capture best practices as we go - eg. what are
sensible proxy connector settings for certain environments vs. just
what they do
- we should add a troubleshooting section: troubleshooting proxy,
troubleshooting webdav
Another important thing is the age old documentation vs site
question: for the things that we get done for 1.0, that should be
*the* documentation for 1.0 (and released with it) - so everything
written above should target a version and be permanent. This would be
deployed somewhere like http://maven.apache.org/archiva/docs/1.0/
For the site:
- we need a good, simple index page. It explains what Archiva is, why
use it, and points to the download and quick start pages to show how
to get it running. It should point at a live demo is we have one
- we should have an external links page listed somewhere to point to
articles, blogs, etc. about Archiva
In fact, I'm going to have a stab at this last one now... hopefully
it'll be done by the time you get this :)
Cheers,
Brett
--
Brett Porter - [EMAIL PROTECTED]
Blog: http://www.devzuz.org/blogs/bporter/
