ant-ivy-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Jean-Claude Cerebro" <jeanclaude.cere...@gmail.com>
Subject Re: documentation
Date Fri, 11 Apr 2008 17:16:09 GMT
Hello Ivy Mailing List,

Based on these responses my feeling is that Xavier is taking the brunt of
the efforts for Ivy and that
we need to be more collaborative in helping solve issues raised.

Looking at the emails it seems that Xavier has a great deal of
domain-specific knowledge for ivy
that needs to be translated into docs on the ivy web site.

My suggestion is that if we end up having issues solved from the mailing
list we translate them into docs
on a ivy web site.

For me, what's lacking is a use-case page because since Ivy is so flexible
without seeing options and
the ways people are doing things, its hard for me to know how best to use
it.

For example Shawn, looks like he just spent six hours or so trying to fix a
cache problem that wasn't apparent from
reading the docs.  Wouldn't this be a great thing to put on the docs in a
more accessible way?

As well as the email with file extensions without artifacts?

Jean-Claude


On Fri, Apr 11, 2008 at 5:58 AM, Roman Legat <roman.legat@gmx.net> wrote:

> I'd like to mention on that:
>
> There is a lot of (good) documentation, which is good starting point. What
> could be
> reworked is the structure. Sometimes it's kind of hard to find the things
> you're looking for.
> What clearly is a mess right now is finding the right documentation for
> the
> version you are using. In some places, the documentation is outdated, or
> tutorials are referring to an older release. The reason for this is that
> ivy currently
> is in the process of becoming 2.0.0 and migrating to apache. So we have to
> live with that for a while until things become more stable.
>
> Nevertheless, it is up to every user to improve documentation, ivy even
> provides
> a rather simple mechanism for changing and sending documentation diffs.
> So, if you
> find a old reference, misspelling, outdated stuff - report it. That saves
> precious time for 2.0.0.
>
> What I am missing are alternative writings on ivy/ivyde besides the
> project documentation. Blogs, tutorial, stuff like that from people using
> ivy. How are you using it? What are your problems, how do you solve them?
> How do you setup your environment?
>
> Roman
>
> -------- Original-Nachricht --------
> > Datum: Fri, 11 Apr 2008 13:32:49 +0200
> > Von: "Xavier Hanin" <xavier.hanin@gmail.com>
> > An: ivy-user@ant.apache.org
> > Betreff: Re: documentation
>
> > 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
> > >
>
> --
> Psst! Geheimtipp: Online Games kostenlos spielen bei den GMX Free Games!
> http://games.entertainment.gmx.net/de/entertainment/games/free
>

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