You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user-java@ibatis.apache.org by Vadim Grinshpun <va...@ll.mit.edu> on 2006/07/06 23:04:30 UTC
developer's guide suggestion (was: Re: GroupBy with simple properties)
> Thanks Tarek. btw which guide are you refering to?
Given the above question, I have a suggestion to the iBATIS team
(apologies in advance if this had been discussed before):
Why not put an conspicuous "Documentation" section on the iBATIS webpage
somewhere(e.g., on the sidebar)? It could simply refer the readers to
the appropriate sections of the download page, but would be easier to
find for the average user ( I know I ran into this problem at first,
and, having been subscribed to the list for a few weeks, I can see
others are doing the same).
Basically, on the current website two things are highly non-obvious to a
newcomer:
1 - that any documentation exists at all. It is unconventional to keep
the docs in the downloads section It doesn't occur to a lot of people to
look there, especially because documentation is typically just an HTML
page, and in the minds of most it simply is not associated with
something you download. (I'm not saying PDF is bad, just saying it's not
what people expect, and thus they don't find it).
2 - that the doc on the site might be out of date and people should look
at the cvs version. Having a relatively up-to-date doc on the site
directly would be even better, but short of that, an easy-to-notice
mention of the CVS version (again, referring to the download page) would
be very helpful.
Hopefully, making these changes should be pretty quick. I think
addressing this issue would preclude a certain fraction of the simpler
"how do I do X"/"please read the manual"/"but where is the manual" type
of exchanges on the list :)
Thanks for listening :)
-Vadim G.
Re: developer's guide suggestion (was: Re: GroupBy with simple properties)
Posted by Jeff Butler <je...@gmail.com>.
+1. I've made some simple changes to the site that will (hopefully) address
this issue.
I've grown weary of trying to explain it too!
Jeff Butler
On 7/6/06, Vadim Grinshpun <va...@ll.mit.edu> wrote:
>
> > Thanks Tarek. btw which guide are you refering to?
>
> Given the above question, I have a suggestion to the iBATIS team
> (apologies in advance if this had been discussed before):
> Why not put an conspicuous "Documentation" section on the iBATIS webpage
> somewhere(e.g., on the sidebar)? It could simply refer the readers to
> the appropriate sections of the download page, but would be easier to
> find for the average user ( I know I ran into this problem at first,
> and, having been subscribed to the list for a few weeks, I can see
> others are doing the same).
>
> Basically, on the current website two things are highly non-obvious to a
> newcomer:
>
> 1 - that any documentation exists at all. It is unconventional to keep
> the docs in the downloads section It doesn't occur to a lot of people to
> look there, especially because documentation is typically just an HTML
> page, and in the minds of most it simply is not associated with
> something you download. (I'm not saying PDF is bad, just saying it's not
> what people expect, and thus they don't find it).
>
> 2 - that the doc on the site might be out of date and people should look
> at the cvs version. Having a relatively up-to-date doc on the site
> directly would be even better, but short of that, an easy-to-notice
> mention of the CVS version (again, referring to the download page) would
> be very helpful.
>
> Hopefully, making these changes should be pretty quick. I think
> addressing this issue would preclude a certain fraction of the simpler
> "how do I do X"/"please read the manual"/"but where is the manual" type
> of exchanges on the list :)
>
> Thanks for listening :)
>
> -Vadim G.
>
>
>
>
Re: developer's guide suggestion
Posted by Vadim Grinshpun <va...@ll.mit.edu>.
Clinton,
I think we're talking about somewhat different things. My suggestion has
to do not with the documentation itself (I understand it's a
work-in-progress, etc), but with the fact that *finding* the
documentation is not very easy on the current website. Hence, I was
pointing out that a few small changes to the *website* would make
everyone's life easier.
That said, I just noticed that the website source is in svn also, so if
I figure out how to build the site, I can try make the changes myself.
(I've never used subversion nor your website's template mechanism, so
there's a learning curve to get over :)
Thanks,
-Vadim
Clinton Begin wrote:
>
> A) Why not use the Wiki. (there's already a "Not Yet Documented" section)
>
> http://opensource.atlassian.com/confluence/oss/display/IBATIS/Home
> <http://opensource.atlassian.com/confluence/oss/display/IBATIS/Home>
>
> B) Why not download the docs, add your improvements and contribute
> them back? The documentation is open and can be edited with free
> tools (Open Office).
>
> http://svn.apache.org/repos/asf/ibatis/trunk/java/docs/
>
> Cheers,
> Clinton
>
>
>
>
>
>
>
> On 7/6/06, *Ben Munat* < bent@munat.com <ma...@munat.com>> wrote:
>
> +1
>
> Vadim Grinshpun wrote:
> > > Thanks Tarek. btw which guide are you refering to?
> >
> > Given the above question, I have a suggestion to the iBATIS team
> > (apologies in advance if this had been discussed before):
> > Why not put an conspicuous "Documentation" section on the iBATIS
> webpage
> > somewhere(e.g., on the sidebar)? It could simply refer the
> readers to
> > the appropriate sections of the download page, but would be
> easier to
> > find for the average user ( I know I ran into this problem at
> first,
> > and, having been subscribed to the list for a few weeks, I can see
> > others are doing the same).
> >
> > Basically, on the current website two things are highly
> non-obvious to a
> > newcomer:
> >
> > 1 - that any documentation exists at all. It is unconventional
> to keep
> > the docs in the downloads section It doesn't occur to a lot of
> people to
> > look there, especially because documentation is typically just
> an HTML
> > page, and in the minds of most it simply is not associated with
> > something you download. (I'm not saying PDF is bad, just saying
> it's not
> > what people expect, and thus they don't find it).
> >
> > 2 - that the doc on the site might be out of date and people
> should look
> > at the cvs version. Having a relatively up-to-date doc on the site
> > directly would be even better, but short of that, an easy-to-notice
> > mention of the CVS version (again, referring to the download
> page) would
> > be very helpful.
> >
> > Hopefully, making these changes should be pretty quick. I think
> > addressing this issue would preclude a certain fraction of the
> simpler
> > "how do I do X"/"please read the manual"/"but where is the
> manual" type
> > of exchanges on the list :)
> >
> > Thanks for listening :)
> >
> > -Vadim G.
> >
> >
> >
>
>
Re: developer's guide suggestion
Posted by Clinton Begin <cl...@gmail.com>.
A) Why not use the Wiki. (there's already a "Not Yet Documented" section)
http://opensource.atlassian.com/confluence/oss/display/IBATIS/Home
B) Why not download the docs, add your improvements and contribute them
back? The documentation is open and can be edited with free tools (Open
Office).
http://svn.apache.org/repos/asf/ibatis/trunk/java/docs/
Cheers,
Clinton
On 7/6/06, Ben Munat <be...@munat.com> wrote:
>
> +1
>
> Vadim Grinshpun wrote:
> > > Thanks Tarek. btw which guide are you refering to?
> >
> > Given the above question, I have a suggestion to the iBATIS team
> > (apologies in advance if this had been discussed before):
> > Why not put an conspicuous "Documentation" section on the iBATIS webpage
> > somewhere(e.g., on the sidebar)? It could simply refer the readers to
> > the appropriate sections of the download page, but would be easier to
> > find for the average user ( I know I ran into this problem at first,
> > and, having been subscribed to the list for a few weeks, I can see
> > others are doing the same).
> >
> > Basically, on the current website two things are highly non-obvious to a
> > newcomer:
> >
> > 1 - that any documentation exists at all. It is unconventional to keep
> > the docs in the downloads section It doesn't occur to a lot of people to
> > look there, especially because documentation is typically just an HTML
> > page, and in the minds of most it simply is not associated with
> > something you download. (I'm not saying PDF is bad, just saying it's not
> > what people expect, and thus they don't find it).
> >
> > 2 - that the doc on the site might be out of date and people should look
> > at the cvs version. Having a relatively up-to-date doc on the site
> > directly would be even better, but short of that, an easy-to-notice
> > mention of the CVS version (again, referring to the download page) would
> > be very helpful.
> >
> > Hopefully, making these changes should be pretty quick. I think
> > addressing this issue would preclude a certain fraction of the simpler
> > "how do I do X"/"please read the manual"/"but where is the manual" type
> > of exchanges on the list :)
> >
> > Thanks for listening :)
> >
> > -Vadim G.
> >
> >
> >
>
Re: developer's guide suggestion
Posted by Ben Munat <be...@munat.com>.
+1
Vadim Grinshpun wrote:
> > Thanks Tarek. btw which guide are you refering to?
>
> Given the above question, I have a suggestion to the iBATIS team
> (apologies in advance if this had been discussed before):
> Why not put an conspicuous "Documentation" section on the iBATIS webpage
> somewhere(e.g., on the sidebar)? It could simply refer the readers to
> the appropriate sections of the download page, but would be easier to
> find for the average user ( I know I ran into this problem at first,
> and, having been subscribed to the list for a few weeks, I can see
> others are doing the same).
>
> Basically, on the current website two things are highly non-obvious to a
> newcomer:
>
> 1 - that any documentation exists at all. It is unconventional to keep
> the docs in the downloads section It doesn't occur to a lot of people to
> look there, especially because documentation is typically just an HTML
> page, and in the minds of most it simply is not associated with
> something you download. (I'm not saying PDF is bad, just saying it's not
> what people expect, and thus they don't find it).
>
> 2 - that the doc on the site might be out of date and people should look
> at the cvs version. Having a relatively up-to-date doc on the site
> directly would be even better, but short of that, an easy-to-notice
> mention of the CVS version (again, referring to the download page) would
> be very helpful.
>
> Hopefully, making these changes should be pretty quick. I think
> addressing this issue would preclude a certain fraction of the simpler
> "how do I do X"/"please read the manual"/"but where is the manual" type
> of exchanges on the list :)
>
> Thanks for listening :)
>
> -Vadim G.
>
>
>