ant-ivy-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Xavier Hanin" <xavier.ha...@gmail.com>
Subject Re: documentation
Date Fri, 11 Apr 2008 11:32:49 GMT
On Thu, Apr 10, 2008 at 2:19 AM, Jean-Claude Cerebro <
jeanclaude.cerebro@gmail.com> wrote:

> Hi Xavier,

Did you notice you sent this e-mail to a mailing list? Why am I the only one
to be fortunate enough to get your greetings ;-)

>
> As a newbie just staring with Ivy I must say that I love Ivy but I'm
> disappointed, not with the capability of Ivy but with the documentation.
>
> Although the level of completeness is very detailed, as a user (customer)
> of
> Ivy I'm finding it very difficult to negotiate simple tasks without having
> to cross-references the examples, the docs, the website, not so clearly
> defined links on the website, and the faq.
>
> In addition, the docs on the website although complete are not clear to a
> user.
>
> I feel that the adoption of ivy in a larger scale hinges on better
> documentation.  Documentation that is dead-simple and presents things in a
> use case fashion that builds on one another that tackles one concept at a
> time and then gets into the more complicated use cases.
>
> Ivy is great and solves a problem really well, the documentation needs to
> distill that in simplistic way.
>
> You may not agree and might be offended at this email and I apologize for
> that but I think someone needs to say this as I would like to see this
> project succeed and become widely adopted in the industry.

I'm not offended at all, it's always good to get feedback from the
community. Now about what I think of the documentation: I think most basic
stuff is explained in tutorials, and should be able to tackle simple use
cases after following the tutorials. Do you think tutorials are not simple
enough?

Once you get the basic level from the tutorials, if you need to go further,
reference documentation should contain answers to most questions. I agree
it's not easy to find your way out of the doc, but it's difficult to create
simple guides or tutorials to every use case, Ivy is so flexible that you
can do many things we don't even always envision ourself. There's also the
mailing list which can be used to ask help from the community. But maybe
you're thinking about one particular topic that would require a guide or
tutorial?

Lastly, this project is open, I don't know if you realize the time Ivy
committer team spend in developing Ivy? And answering questions? And
updating the reference documentation with every single change in Ivy
features? Maybe writing some more tutorials and introductory material could
deserve some participation from users? from you?

Xavier

>
>
> Jean-Claude
>



-- 
Xavier Hanin - Independent Java Consultant
http://xhab.blogspot.com/
http://ant.apache.org/ivy/
http://www.xoocode.org/

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message