archiva-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brett Porter <br...@apache.org>
Subject Re: [Update 1] Documentation for 1.0
Date Sun, 11 Nov 2007 03:42:59 GMT
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 - brett@apache.org
Blog: http://www.devzuz.org/blogs/bporter/


Mime
View raw message