I think people find it easier to read some proza interleaved with code snippets (like the tutorials we already have) then to read code with a lot of comments. At least as an introduction, for the more advanced stuff we could indeed point to some code with comments.
I agree with Trustin about the step-by-step approach, if time was on my side ... I still need to have a look at the code attached to https://issues.apache.org/jira/browse/DIRMINA-227 Maarten On 10/19/07, Mark < [EMAIL PROTECTED]> wrote: > > as for the examples, maybe we need to add a whole lot of comments to the > code. > > On 10/19/07, Trustin Lee <[EMAIL PROTECTED]> wrote: > > On 10/18/07, Maarten Bosteels <[EMAIL PROTECTED]> wrote: > > > Hi, > > > > > > I was actually thinking about splitting up the documentation > completely > > > like they did for tomcat : http://tomcat.apache.org/ > > > > > > Idea is that once you click on "documentation 2.0" you would only see > > > the docs for 2.0 > > > and vice versa. > > > > > > But maybe we can start with spliting up the sections one by one, like > > > you did with the Quick guide. And reorganize later. > > > > > > Is that ok with everybody ? > > > > I'd love to see the change. > > > > Additionally, we need to provide a series of tutorials to show how > > MINA application is developed. For example we could guide users like > > the following: > > > > 1) Show the simple echo server. > > 2) Show some feature like timeout, future, ... > > 3) Apply codec > > 4) Apply thread model > > 5) JMX & Spring integration > > > > and then people will start to look into more advanced tutorial which > > is focused to a certain topic. > > > > For now, our documentation is too fragmented, and that's why we are > > getting a lot of questions. :) > > > > WDYT? > > > > Trustin > > -- > > what we call human nature is actually human habit > > -- > > http://gleamynode.net/ > > -- > > PGP Key ID: 0x0255ECA6 > > > > > -- > -------------------------------- > The adjuration to be "normal" seems shockingly repellent to me; I see > neither hope nor comfort in sinking to that low level. I think it is > ignorance that makes people think of abnormality only with horror and > allows them to remain undismayed at the proximity of "normal" to > average and mediocre. For surely anyone who achieves anything is, > essentially, abnormal. > Dr. Karl Menninger >
