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

[David M. Lloyd]

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