Mailing-List: contact users-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: users@cocoon.apache.org
Received-SPF: pass (hermes.apache.org: local policy)
Message-Id: <s25e1ee4.095@cs-emo.csir.co.za>
Date: Thu, 14 Apr 2005 07:42:08 +0200
From: "Derek Hohls" <dhohls@csir.co.za>
To: <users@cocoon.apache.org>
Subject: Re: State of the documentation effort
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

Reinhard

The broad structure seems fine; and I think the brutus
site should reflect this i.e. there is currently a=20
'Tutorial', 'Documentation' and 'Blocks' tabs; maybe
add/change these to :
'Getting Started','Tutorials', 'Reference Docs' (with
blocks being a subtopic under Reference Docs=20
(obviously the topic will be mentioned in lesser detail
under the other sections).

And this leads to the point I was trying to make; these
main tabs need to be broken down further - Ref Docs
will obviously keep the same structure as existing site
(with some additions) and, argubly, most new doc work
must go into the "Getting Started" section.  Again,=20
there have been detailed suggestions made in the
past and documented on the wiki that can be used as
good starting points.

Thanks
Derek

>>> reinhard@apache.org 04/13/05 4:42 PM >>>
Derek Hohls wrote:
> Reinhard
>=20
> This looks good - what still seems to be missing is an=20
> overall information structure - the "wood" and not the
> "trees" - for me, assessing the detail is much easier if
> I can see the big picture.  I also think it makes it easier
> to see if new pages eg. from the wiki, need to be added
> in to help complete the information structure.

Our goal is providing three types of documentation:

   - getting started infos
   - reference docs
   - tutorials (as suggested today)

The current state of our work is accesible through=20
http://brutus.apache.org/docs/build/cocoon-2-2/index.html. Tommorrow the =
legacy=20
tab will be filled with all 2.1 docs that have to be reviewed.

>=20
> [sidebar: it is suggested on the page :
> http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo=20
> that users should "add a note at the top of the page that=20
> you're working on moving it to our official documentation"
> how about allowing users to suggest pages that should be
> moved, and let the docs team decide if they need work on?
> Maybe try and have standard way of annotating this?]

maybe it would be more helpful to have a wiki page that links to all =
suggested=20
pages with a comment who is working on it and what's the current state.

WDYT?


--=20
Reinhard P=F6tz           Independent Consultant, Trainer & (IT)-Coach=20

{Software Engineering, Open Source, Web Applications, Apache Cocoon}

                                        web(log): http://www.poetz.cc
--------------------------------------------------------------------


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org