[jboss-dev] AS6 Documentation Update

[Stan Silvert]

Brian Stansberry wrote:
> Can this be discussed on jboss-dev instead of privately? Community 
> feedback could be useful.
Sure.  I wanted to be careful at first, but I'll copy both lists from 
now on.
>
> I like the basic structure. :)
>
> What are your thoughts re: versioning? Separate subspace per version?
It won't strictly be Spaces, since we'll be using Magnolia instead of 
Clearspace.  But whether or not we will have a similar concept of a 
space for each version is an open question.  DocBook versioning is 
relatively simple because the source is held in SVN.  For the static 
pages, I'm not sure what will happen.  I think it's probably a question 
better left to the time when we get closer to completion of AS6.0.0.GA.
>
> On 01/18/2010 08:19 AM, Stan Silvert wrote:
>> I want to fill everyone in on where we are with this project.  I was
>> able to have a nice talk with Mark Newton, who set me straight on
>> tooling. What I didn't realize was that ClearCase is not the right tool
>> for building the site used to find our documents. Right now, we have
>> this wiki-style page:
>> https://community.jboss.org/wiki/JBossApplicationServerOfficialDocumentationPage 
>>
>>
>> I've felt all along that we need something more comprehensive than just
>> a few links to a few documents. We need a site that organizes everything
>> a user needs to get things done with AS6. This not only includes
>> "Getting Started" and "Admin" guides, but also includes things such as
>> javadoc, sample code, and JEE spec info. For these static pages that
>> organize the content, Magnolia is the right tool.
>>
>> So, the three tools we will use are:
>> *DocBook for Content: * We've already discussed this. The content will
>> be done primarily in DocBook.
>> *Magnolia for Doc Site:* We will have an AS6 documentation site broken
>> up into several sections that roughly reflects the structure of the
>> development teams.
>> *ClearCase for Feedback: *ClearCase is really meant as a collaboration
>> and feedback tool. A nice feature Mark told me about is that you can
>> embed a bit of javascript onto any html page and allow a ClearCase
>> discussion about the page. So we can do this for the HTML version of all
>> our DocBook content and get feedback on each page.
>>
>> Almost everyone who writes code that goes into AS will need to write
>> some community documentation using DocBook. The strategy here is divide
>> and conquer. We will break up much of the existing docs into smaller
>> chunks and add new chunks as we go.
>>
>> Here is how I see the documentation being laid out on the web site. The
>> site outlined here is not set in stone, nor is it comprehensive:
>>
>> *Main Doco Page:* Mostly just contains links to the subsections below.
>>
>> *AS6 Core Sections* (Each has its own static HTML page created in 
>> Magnolia)
>>
>>     * AS6 Core Getting Started Page
>>     * Tools Page (like Twiddle and JMX Console)
>>     * Administration and Tuning Page
>>     * Core Architecture Page
>>     * Security Page
>>
>> *AS6 Component Sections* (each has its own static HTML page created in
>> Magnolia)
>>
>>     * Messaging
>>     * Clustering
>>     * Remoting
>>     * Transactions
>>     * Web Services
>>     * Web Container
>>     * JSF
>>     * EJB
>>     * Weld
>>     * etc.
>>
>> Each of the pages above contain links to DocBook pages, javadoc, specs,
>> etc. I'll be building out a skeleton site this week and I'll figure out
>> how we can get it published for all to see. When that is done we will
>> all have something to look at and then we can talk more specifically
>> about content.
>>
>> *But each developer can help with this starting now.* If you write code
>> that eventually makes it into AS6 then please start thinking about the
>> user documentation. Think about what a community user needs to know
>> about to use your code in AS6. Even start writing some doc if you 
>> have time.
>>
>> More to follow.
>>
>> Stan
>>
>>
>
>