cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Derek Hohls" <dho...@csir.co.za>
Subject Re: State of the documentation effort
Date Thu, 14 Apr 2005 05:42:08 GMT
Reinhard

The broad structure seems fine; and I think the brutus
site should reflect this i.e. there is currently a 
'Tutorial', 'Documentation' and 'Blocks' tabs; maybe
add/change these to :
'Getting Started','Tutorials', 'Reference Docs' (with
blocks being a subtopic under Reference Docs 
(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, 
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
> 
> This looks good - what still seems to be missing is an 
> 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 
http://brutus.apache.org/docs/build/cocoon-2-2/index.html. Tommorrow the legacy 
tab will be filled with all 2.1 docs that have to be reviewed.

> 
> [sidebar: it is suggested on the page :
> http://wiki.apache.org/cocoon/CocoonDocumentationSystemHowTo 
> that users should "add a note at the top of the page that 
> 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 
pages with a comment who is working on it and what's the current state.

WDYT?


-- 
Reinhard Pötz           Independent Consultant, Trainer & (IT)-Coach 

{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


Mime
View raw message