Re: [jboss-dev] AS6 Documentation Update
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/JBossApplicationServerOfficialDocumentat...
>
>
> 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
>
>