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 Ersin Er <er...@cs.hacettepe.edu.tr> on 2005/06/06 19:59:19 UTC
[iBatis] Documentation
Hi,
Is there any plan for a major update for iBatis SQL Mapper documentation?
Thanks.
--
Ersin Er
Re: [iBatis] Documentation
Posted by Brandon Goodin <br...@gmail.com>.
excellent! thanks Ersin.
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> > Finally, don't forget... you have the power to help.
> >
> > Brandon
>
> OK. I'll try to produce a sample section.
>
> --
> Ersin
>
Re: [iBatis] Documentation
Posted by Clinton Begin <cl...@gmail.com>.
Ersin,
Feel free to use the wiki to fill in content for the undocumented features,
or the examples. Only if it's easier for you though. Otherwise, you can
download the Open Office documents from our subversion repository.
Cheers,
Clinton
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
>
> > Finally, don't forget... you have the power to help.
> >
> > Brandon
>
> OK. I'll try to produce a sample section.
>
> --
> Ersin
>
Re: [iBatis] Documentation
Posted by Ersin Er <er...@cs.hacettepe.edu.tr>.
> Finally, don't forget... you have the power to help.
>
> Brandon
OK. I'll try to produce a sample section.
--
Ersin
Re: [iBatis] Documentation
Posted by John Fereira <ja...@cornell.edu>.
At 03:41 PM 6/6/2005, Brandon Goodin wrote:
> If you want to help out, then you have the power
>to do so. The responsibility is not solely on the committers. We
>definitely want to be more user friendly. Let's all pitch in and help
>it to be better.
>
>
>"I appreciate the current condition of the documentation as being a
>open source project, but it should be better"
>
>I agree. You should pitch in and help make it better.
I realize this thread has mostly died but I wanted to chime in here (I
would have done it sooner but I have some storm damage at home to deal with).
For the past three years I have contributed to another collaborative open
source project that probably has many more contributors and very wide
spread usage (uPortal) as the documentation coordinator. Although I have
contributed quite a bit of the documentation myself there is no way I could
possibly create the complete set of documentation required, and especially
keep it up to date as the product evolves. So, for the most part I have my
to rely on the committers (those actually writing the code) to document
their work and most of them are pretty good about it. My "job" (which is
entirely done on a volunteer basis...I have several other project that I am
actually paid to work on) is to coordinate their efforts.
Like the iBatis project we've got a few mailing lists and a primary web
site. Last year, we started using Confluence and Jira. As a result,
"documentation" is scattered about on the main web site, some fairly
dynamic content on the wiki, and many existing issues are documented in the
Jira comments. Coincidentally this weekend I am doing a uPortal
documentation roadmap presentation at the uPortal conference which will
attempt to identify all the different places where one can find
documentation related to uPortal and a portion of the presentation will be
devoted to making a plea to those implementing uPortal at their own
institutions to get involved; to contribute to the wiki, log issues in
Jira, and document their experiences so that the overall documentation can
be improved.
Re: [iBatis] Documentation
Posted by Brandon Goodin <br...@gmail.com>.
Let's not start a flame here. Please keep your criticisms constructive
and away from the edge of insulting. The bottom line is that we should
all appreciate constructive criticism. The documentation is excellent
even compared to many commercial products on the market and it can
ALWAYS be improved. If you want to help out, then you have the power
to do so. The responsibility is not solely on the committers. We
definitely want to be more user friendly. Let's all pitch in and help
it to be better.
"I appreciate the current condition of the documentation as being a
open source project, but it should be better"
I agree. You should pitch in and help make it better.
"For example, on page 27, a Category - Product example is given for Complex
Collection Properties. On the next page the iBatis solution is given with
a different example. I'd like to see the same example enhanced (ofcourse
the primary example could be a more complex one to demonstrate the
benefit)."
I think you are being picky here. The real question is. Did you
understand what it was and did you grasp how to use it?
"For example, I'd like to see a more pure JDBC Compared approach (at least
a few examples) for showing the iBatis value."
This would be a great comparison. But, i would consider this to be
another document. It would be more of a comparative look at straight
JDBC and iBatis.
"I cannot catch the big picture really (may be because of not being a
native English speaker)."
Perhaps. But, do you understand the big picture now? What would help
you to understand the big picture more?
"And lastly I'd like to see the document in HTML"
HTML is a great idea.
" with a more beautiful and better layout :)"
Sorry friend, but, gimme a break. The layout is fine.
"and 2.1.0 features. Lastly as being an Apache Project, I think, the
documentation needs at least some informational changes to reflect the
current state."
Good point. Maybe we should include the not yet documented section
into the documentation.
Finally, don't forget... you have the power to help.
Brandon
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> > Whoooooaaaaaaoooo:
> >
> > One of the great attributes of iBatis is its documentation.
> >
> > I have seen commercial products that do not measure to the well organized
> > and detailed documentation ofiBatis an Open Source based product.
>
> I appreciate the current condition of the documentation as being a open
> source project, but it should be better.
>
> > For the authors and for us users of iBatis, it will be beneficial for you
> > to
> > clarify:
> >
> > 1. Organization of the material. How is it that you perceive the
> > available material as disorganized?
>
> For example, on page 27, a Category - Product example is given for Complex
> Collection Properties. On the next page the iBatis solution is given with
> a different example. I'd like to see the same example enhanced (ofcourse
> the primary example could be a more complex one to demonstrate the
> benefit).
>
> For example, I'd like to see a more pure JDBC Compared approach (at least
> a few examples) for showing the iBatis value.
>
> I cannot catch the big picture really (may be because of not being a
> native English speaker).
>
> And lastly I'd like to see the document in HTML with a more beautiful and
> better layout :)
>
> > 2. Undocumented features. What features are you trying to use for
> > which information is unavailable.
>
> http://opensource.atlassian.com/confluence/oss/display/IBATIS/Not+Yet+Documented
>
> and 2.1.0 features. Lastly as being an Apache Project, I think, the
> documentation needs at least some informational changes to reflect the
> current state.
>
> Thanks.
>
> --
> Ersin
>
> > jfz.
> >
> > On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> >>
> >> > is there a reason for a major update to the ibatis sql mapper
> >> > documentation?
> >>
> >> I think yes. It seems to be unorganized and there are undocumented
> >> features, to me..
> >>
> >> --
> >> Ersin
> >>
> >>
> >> > On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> >> >> Hi,
> >> >>
> >> >> Is there any plan for a major update for iBatis SQL Mapper
> >> >> documentation?
> >> >>
> >> >> Thanks.
> >> >>
> >> >> --
> >> >> Ersin Er
> >> >>
> >> >
> >>
> >>
> >
>
>
Re: [iBatis] Documentation
Posted by Ersin Er <er...@cs.hacettepe.edu.tr>.
> Whoooooaaaaaaoooo:
>
> One of the great attributes of iBatis is its documentation.
>
> I have seen commercial products that do not measure to the well organized
> and detailed documentation ofiBatis an Open Source based product.
I appreciate the current condition of the documentation as being a open
source project, but it should be better.
> For the authors and for us users of iBatis, it will be beneficial for you
> to
> clarify:
>
> 1. Organization of the material. How is it that you perceive the
> available material as disorganized?
For example, on page 27, a Category - Product example is given for Complex
Collection Properties. On the next page the iBatis solution is given with
a different example. I'd like to see the same example enhanced (ofcourse
the primary example could be a more complex one to demonstrate the
benefit).
For example, I'd like to see a more pure JDBC Compared approach (at least
a few examples) for showing the iBatis value.
I cannot catch the big picture really (may be because of not being a
native English speaker).
And lastly I'd like to see the document in HTML with a more beautiful and
better layout :)
> 2. Undocumented features. What features are you trying to use for
> which information is unavailable.
http://opensource.atlassian.com/confluence/oss/display/IBATIS/Not+Yet+Documented
and 2.1.0 features. Lastly as being an Apache Project, I think, the
documentation needs at least some informational changes to reflect the
current state.
Thanks.
--
Ersin
> jfz.
>
> On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
>>
>> > is there a reason for a major update to the ibatis sql mapper
>> > documentation?
>>
>> I think yes. It seems to be unorganized and there are undocumented
>> features, to me..
>>
>> --
>> Ersin
>>
>>
>> > On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
>> >> Hi,
>> >>
>> >> Is there any plan for a major update for iBatis SQL Mapper
>> >> documentation?
>> >>
>> >> Thanks.
>> >>
>> >> --
>> >> Ersin Er
>> >>
>> >
>>
>>
>
Re: [iBatis] Documentation
Posted by "J.F. Zarama" <jf...@gmail.com>.
Whoooooaaaaaaoooo:
One of the great attributes of iBatis is its documentation.
I have seen commercial products that do not measure to the well organized
and detailed documentation ofiBatis an Open Source based product.
For the authors and for us users of iBatis, it will be beneficial for you to
clarify:
1. Organization of the material. How is it that you perceive the
available material as disorganized?
2. Undocumented features. What features are you trying to use for
which information is unavailable.
jfz.
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
>
> > is there a reason for a major update to the ibatis sql mapper
> > documentation?
>
> I think yes. It seems to be unorganized and there are undocumented
> features, to me..
>
> --
> Ersin
>
>
> > On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> >> Hi,
> >>
> >> Is there any plan for a major update for iBatis SQL Mapper
> >> documentation?
> >>
> >> Thanks.
> >>
> >> --
> >> Ersin Er
> >>
> >
>
>
Re: [iBatis] Documentation
Posted by Brandon Goodin <br...@gmail.com>.
Ersin,
That is true. There are some undocumented features. If there is
anything that you see that is not in the documentation, please feel
free to submit a patch. We are thrilled to include any valuable
contributions into the docs. I do apologize for some of the features
that are not documented. But, any help is appreciated. That being
said, iBatis does have pretty comprehensive documentation. I wouldn't
say we need a major update. We simply need to add some undocumented
features. Not sure if you have the current documentation that includes
a table of contents.
Brandon
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> > is there a reason for a major update to the ibatis sql mapper
> > documentation?
>
> I think yes. It seems to be unorganized and there are undocumented
> features, to me..
>
> --
> Ersin
>
>
> > On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> >> Hi,
> >>
> >> Is there any plan for a major update for iBatis SQL Mapper
> >> documentation?
> >>
> >> Thanks.
> >>
> >> --
> >> Ersin Er
> >>
> >
>
>
Re: [iBatis] Documentation
Posted by Ersin Er <er...@cs.hacettepe.edu.tr>.
> is there a reason for a major update to the ibatis sql mapper
> documentation?
I think yes. It seems to be unorganized and there are undocumented
features, to me..
--
Ersin
> On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
>> Hi,
>>
>> Is there any plan for a major update for iBatis SQL Mapper
>> documentation?
>>
>> Thanks.
>>
>> --
>> Ersin Er
>>
>
Re: [iBatis] Documentation
Posted by Brandon Goodin <br...@gmail.com>.
is there a reason for a major update to the ibatis sql mapper documentation?
On 6/6/05, Ersin Er <er...@cs.hacettepe.edu.tr> wrote:
> Hi,
>
> Is there any plan for a major update for iBatis SQL Mapper documentation?
>
> Thanks.
>
> --
> Ersin Er
>