Documentation

[esteve]

Hi, I have been reading Seam 3 documentation. I know that it is not finished yet, but I have a few comments about it that I think they can improve it.

First, the documentation is pretty large (hard to swallow). Second, it is clear that every module member has done its own part so that it is hard to follow if you follow the index. Third, it doesn't seam to be intended to be used for developers, it seams it is targeted for software arquitects. Finally, if you read all the documentation you are not granted to have an application successfully deployed.

So my conclusion is as follows: · Reduce it for the sake of simplicity · Glue it from the perspective of a software developer, including example references and focusing on giving technical and functional problems resolved. · Order the chapters from most importance to less importance based on the usage (it will be more used persistence than JMS)

I expect my comments will help improve seam 3.

Thanks,

[matkapx]

Totally agree with you,
I had stated a fresh project with EE 6 and CDI i wanna extend with seam 3. But because of current documentation i was not success to develop with Seam 3 ( and modules)

Hope community would work on pretty , effective documentation.

[pgmjsd]

Good comments.   Hoping is nice, but contributing documentation is better. :)

[lightguard]

Joshua Davis wrote on Jul 14, 2011 12:57:


Good comments.   Hoping is nice, but contributing documentation is better. :)

I couldn't agree with this more

[bleathem]

If we could get some community members contributing documentation, that would free up dev's time to implement new features.  There requires a flow of information between the devs and those writing the documentation, but we should be able to work something out there.  This direct developer communication would be an advantage for document writers.

Also, we need to make it easier to write documentation.  Writing/editing documentation is orders of magnitude easier in a wiki than it is with docbook xml.  Let's drop the docbook documentation requirement, and move to something with a lower barrier of entry!

Brian

[pgmjsd]

Brian Leathem wrote on Jul 14, 2011 16:03:

Also, we need to make it easier to write documentation.  Writing/editing documentation is orders of magnitude easier in a wiki than it is with docbook xml.  Let's drop the docbook documentation requirement, and move to something with a lower barrier of entry!

Agreed. I usually write my notes and documentation on my own wiki for exactly that reason.   I'd definitely use a shared wiki if it was available to me.

For example, I have the dubious distinction of having documented 'page.xml'.  Search for 'pages.xml', and Google shows my wiki as the first result

[andrewwheeler]

I would like to chip in and give my support for a rethink of the documentation methodology. As has previously been said a change in focus towards the developer with more examples and how-to guides to solve common problems. Secondly, I would also like to see every feature documented. If someone has taken the time to write the code surely it is worth explaining how it works. Java Docs are OK, but sometimes they really don't give you a picture of how it works.

[lightguard]

Andrew Wheeler wrote on Jul 15, 2011 20:46:


I would like to chip in and give my support for a rethink of the documentation methodology. As has previously been said a change in focus towards the developer with more examples and how-to guides to solve common problems. Secondly, I would also like to see every feature documented. If someone has taken the time to write the code surely it is worth explaining how it works. Java Docs are OK, but sometimes they really don't give you a picture of how it works.

Please come to the Seam Community meeting Wednesday 22:00 UTC and we'll discuss documentation and what we can do to make it better.