portals-jetspeed-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ron Wheeler <rwhee...@artifact-software.com>
Subject Re: [jira] Commented: (JS2-83) Site Documentation, Architectural Overview
Date Sun, 20 Nov 2005 20:20:48 GMT
Since I do not know very much, I am pretty easy on the structure.
I broke the "getting started" down to
    an introduction
    getting started with binary
    getting started with source - not touched yet
    The "getting started with binary" focuses on the main flow and the 
material that was previously in-line is now in separate pages. The 
original format was too complex and the in-line bits were abridged to 
keep them short so they did not include all the information relating to 
the topics.

The biggest problem that people seem to have is getting the software up 
and running and doing the simple customization.
The "binary" installation probably needs to be repackaged with tasks 
that will actually do what I have suggested (if I am right).

I am not wildly enthusiastic about aWiki as a source of official 
documentation since it is difficult to maintain 2 documentation streams 
and keep them in synch. On the other hand it is a good place for users 
to document their development experiences and provide tips and such.

I do not understand the part about PDFs. I think that the WWW site with 
HTML from xdocs is probably the focus.
Can we set up the xdocs so that a table of contents/site map is 
automatically generated?

Have you looked at the stuff that I did on jetspeed.artifact-software.com?
I have had a hard time getting any feedback about whether the 
installation strategy is correct. I also need some input about who 
should be using a source install versus a binary install - if there is 
any need to have a "binary" install.


David Le Strat (JIRA) wrote:

>    [ http://issues.apache.org/jira/browse/JS2-83?page=comments#action_12358074 ] 
>David Le Strat commented on JS2-83:
>As part of this exercise, I would like to propose reorganizing the documentation structure
a bit:
>1.  We should differentiate the role of the main site from the role of the subprojects
sites.  I propose that we locate each subproject documentation in the matching component xdocs.
 For instance, profiler goes into /components/profiler/xdocs.   Each subproject has a PDF
document that can be exported for the relevant section.  The subproject documentation focus
on the implementation aspects of a specific component.
>The role of the main site is to provide guidance in locating the documentation for each
component and to provide reference docs that cut across components.
>2.  I would like to reorganize the main docs navigation as follow:
>         Features
>         Installation
>         Getting Started
>         Subprojects
>         Binaries
>         Source Code
>         Documentation Guides -> Links to a page with an organized list of documentation
guides - The guides provide a quick list of references/links to resources around a specific
topic, when necessary the guide will link to the relevant documentation in the sub project.
  For instance Guide to Developing Portlets, Guide to Customizing Pages, Guide to Jetspeed
Pipeline,  etc.
>         Jetspeed API
>         Jetspeed Plugin
>Key Components
>         Profiler
>         Page Manager
>         Security
>         etc.
>These are links to the subproject pages from the main page.  Another option is to centralize
those into a Guide to J2 Components (see above) and a better option in my opinion.
>About J2
>        FAQ
>        For J1 Users
>        Supporting Projects (Bridge, Pluto, Apache DS, Derby, Maven, etc...)
>        Who Uses J2
>        Portlets Community
>        How to Help
>        Mailing List
>        Bug Database
>        Wiki
>        Quality Testing
>        Source Code Repository
>I look forward to your input.  Once we have a consensus on the docs structure, I will
start putting the pieces in place. 
>We already started to track the larger documentation effort under
>Once we are in agreement on the structure I will create additional subtasks for people
to sign up in the parent task.
>>Site Documentation, Architectural Overview
>>         Key: JS2-83
>>         URL: http://issues.apache.org/jira/browse/JS2-83
>>     Project: Jetspeed 2
>>        Type: Task
>>  Components: Site Documentation
>>    Versions: 2.0-FINAL
>>    Reporter: David Sean Taylor
>>    Assignee: David Le Strat
>>     Fix For: 2.0-FINAL
>>Architectural Overview of Jetspeed-2, publish to Jetspeed-2 site

To unsubscribe, e-mail: jetspeed-dev-unsubscribe@portals.apache.org
For additional commands, e-mail: jetspeed-dev-help@portals.apache.org

View raw message