> <snip...>
> 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.
>
I'm not sure I agree that Jonathan's document is not good as a user manual. Yes it certainly needs some extra chapters, especially an overview, and a bit of rework. However (and I'm speaking as a trained sports coach) the majority of people learn much better in an example driven environment. What I have tended to find is that the top few percent of computer people (like those who tend to work on open source projects) tend to have a different way of learning that is more detail oriented. I personally learn much more quickly from reading reference manuals than I do from reading user documents.
I think the key is to have two different documents that focus on the two different styles of learning. One document (the User Guide?) should approach Wicket from a "This is what you can do with Wicket and here's how you do it" point of view, with lots of examples, full source code listings and so on. The second document (the Reference Manual?) should approach Wicket from a "This is how Wicket works and here's all the detail you need to get the most out of it".
Personally I would skim read the User Guide and then switch straight to the Reference Manual. However, I know many developers who would read the User Guide from cover to cover and then just use the Reference Manual only when they need to look up some detailed information.
> 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 ;-)
>
+1 on most of this. I do think that the User Guide should contain either lots of fully worked examples or a single example that builds up throughout the document (e.g. CD App?) to show all of the main features of Wicket and with code that readers can copy and paste into their own applications. This would be very consistent with the approach taken by many '... In Action' type books. I also don't think the User Guide should expend too much effort explaining how Wicket works, instead if should focus on how Wicket makes developing web applications easy.
I think the "Creating your own component" chapter should be fairly minimal and focus more on building reusable application level components (e.g. login forms, headers, footers) as opposed to developing new complex components (e.g. trees, paged tables). Building new complex components should be dealt with by the Reference Manual.
I also think that the User Guide should probably not go into large amounts of detail on things like scalability (e.g. DetachableModels and so on) and all of the minor details of Wicket configuration. It should mention what is possible and then refer the user to the Reference Manual for full details on how to do it.
> >
> I find that wiki's tend to distract from the really 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.
>
I certainly don't think the Wiki should either duplicate or replace anything in the User Guide or Reference Manual. However it should be the place where we talk about how Wicket integrates with other products (JDO, Spring Framework, JSP), how to convert from other frameworks to Wicket and so on. It's also a good place where users of Wicket can contribute their experiences, talk about how they solved certain problems or expand on best practices. The advantage being that it will keep the User Guide and Reference Manual much more stable and focused.
Regards,
Chris
