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 Ben Munat <be...@munat.com> on 2006/07/07 05:38:01 UTC
Re: developer's guide suggestion
+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 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.
> >
> >
> >
>