Christopher Turner wrote:
I've come up with a preliminary contents for the user's guide. I find the Jonathan document not too good for a user's manual. It is too much example driven and lacks a clear overview, and the usage scenario's of aspects of webapplication programming using wicket.Hi Everyone,
As we are approaching a 1.0 release I'm sure we are all agreed on the need for documentation. I've been looking at a number of other well-documented projects (e.g. Spring Framework, Hibernate and similar) and I have noticed that they all seem to have certain traits in common:
1) A 'Quickstart Guide' explaining how to install and get up and running with a basic project
2) A 'User Guide' which is easy to read and allows developers to learn the product in an example driven way
On the style-1 site I've posted a new contents overview which I'll repeat here for further discussion:
* Introduction
* The architecture
* A simple Wicket application
* The Wicket framework
* Creating your own component
* Internationalization
* Testing Wicket applications
* Component reference
I'd say it should be somewhat of a 'Wicket In Action' book. It's a shame we won't be able to profit from it ;-)
3) A 'Reference Manual' that explains all of the features of the product in detail with snippets of examplesI find that wiki's tend to distract from the realy manual. I would vote against a wiki if a vote comes up. I really hate it when I've got to look in 7 or 8 different places to find information. Wiki's also tend to have outdated information.
4) A 'WIKI' that allows users to contribute to the documentation with experiences, code examples and so on
We seem well on the way to having 1 and 2, although the User Guide needs significant rework and updates to cover all of the recent changes and additions. Having a WIKI is I think very valuable, but perhaps not something that should divert resources from documentation and testing for the time being.
My main interest is in the Reference Manual. I personally don't learn particularly well from example driven books or guides. I like to have things explained to me in detail. I'm also pretty poor at writing example driven stuff as I tend to dive into too much explanation! I'm therefore - I think ;) - volunteering to start work on a Reference Manual. If everyone agrees with me doing this I'll sketch out a table of contents and post it up for comments.
+1
Martijn
------------------------------------------------------- This SF.Net email is sponsored by: Sybase ASE Linux Express Edition - download now for FREE LinuxWorld Reader's Choice Award Winner for best database on Linux. http://ads.osdn.com/?ad_id=5588&alloc_id=12065&op=click _______________________________________________ Wicket-develop mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/wicket-develop
