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

[Peter Muir]

Hmm let me think about faqs. Maybe with online docs it makes sense to put them in an appendix. Main reason I'm hesitant is that the style is very different to the rest of the guide, which is tutorial style.

These samples are complete projects with builds etc for the user to play with. Each class/file is discussed inline with docs.

We could move the code to a dedicated quickstarts repo if needed.

One final thing to mention is the Dev gsg comes with an ee6 archetype, this makes most sense in it's own repo (distinct lifecycle).

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

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

> Okay, the fourth guide would be under the "admin" heading then as well, so that gives us one each admin and developer quick start guide and one each admin and developer reference guide.  That works for me.
> 
> As for a FAQ style document, I'm not sure it would make sense to publish it into a book by itself, but we could have an "Uncategorized" heading for now I guess (much as I hate the "junk drawer" concept) and worry about that later.
> 
> Code should live in Git, I guess; we would produce tags which correspond to each book release.  Note that code samples can also exist in-line (of course) if they're of acceptable size.
> 
> On 06/15/2011 10:49 AM, Peter Muir wrote:
>> 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
> 
> 
> -- 
> - DML