10:49 a.m.
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(a)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