ibatis-user-java mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vadim Grinshpun <va...@ll.mit.edu>
Subject Re: developer's guide suggestion
Date Fri, 07 Jul 2006 16:14:37 GMT
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 <mailto:bent@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.
>     >
>     >
>     >
>
>


Mime
View raw message