[jboss-as7-dev] Time to get on the same "page" with docs

[Peter Muir]

I have thought about the names a bit, and I think they are wrong. I propose we need 4 guides:

* getting started guide - server layout, logging config, deploy a datasource, intro to cli, intro to management web console. Shelly is working on this.

* getting started developing apps - my guide

* admin reference guide

* developer reference guide

Note I've really just changed some names a bit. We could merge 1&2 if needed, but I think they have value separately.

I also would not put "how do I do..." stuff in the getting started guide. I think this lives better in an FAQ style document. Not only does this format work better, it's also where people expect it to be - principle of least surpirse :-)

Then eventually we would have a JBoss AS developer tutorial which is very much about how you an write more complex apps.

Regarding confluence, I don't much mind if you use that, as ive said all along once I have a final draft of the guide more than happy for someone to move it to the right place. I need to make a few more edits, so give me until the end of the week to get a final draft.

I also have quickstarts which are code, these can't live on confluence so where do you want these?

--
Pete Muir
http://in.relation.to/Bloggers/Pete

On 15 Jun 2011, at 17:28, "David M. Lloyd" <david.lloyd at redhat.com> wrote:

> We have a fairly small window available to us to get our AS 7 documentation together.  So far, we have a bunch of miscellaneous Confluence pages in various state of repair and a docbook repository for a developer quick start which is reasonably underway, as well as possibly other docbook repositories which have been begun by various parties.
> 
> Before we invest too much in these disparate architectures, it's time to hit the brakes and make sure we're all going in the same direction here.
> 
> It has been decided that our community documentation for AS 7 will be hosted in Confluence.  The process for generating the final documentation files will be driven from here.
> 
> This means that we need a real page structure here.  The top-level documents ("books") we should define are currently:
> 
> * Developer Quick Start Guide (Pete's guide)
> * Administration Guide
> * Developer Reference Guide
> 
> The Developer Quick Start Guide is, in addition to Pete's stuff, probably where the "How do I ...?" question sections should go.  Jim, this will be up to you to complete, otherwise we'll probably drop these pages (most of them do not contain much if any content currently).  This guide is the top priority; if we have no other document ready by the final 7.0 release, we should at least have this one.  This means that the docbook structure(s) we currently have should be imported and cleaned up ASAP.
> 
> The Administration Guide is where we'd put descriptions of the configuration file, operation descriptions, and how to perform operations from the CLI and web console.  Much of this guide can probably be generated programmatically out of our operation descriptions, at least for the initial version.
> 
> The Developer Reference Guide will cover details of every deployment descriptor, annotation, and API we make available to deployments.  It should also cover embedding, eventually, and would be the place where we put more esoteric stuff.
> 
> Once these three docs are complete, it would be really nice to ultimately have a "JavaEE howto" guide to get people started with JavaEE development, from an EE6 perspective (EJB3, CDI, etc.), but this is clearly a much lower priority.
> 
> Questions?
> -- 
> - DML