ant-ivy-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Brown, Carlton" <Carlton.Br...@compucredit.com>
Subject RE: documentation
Date Fri, 11 Apr 2008 17:46:36 GMT
I find the documentation is fairly complete in terms of content.  It's
much better than some projects I could mention.  However, in many places
it lacks context and organization.  It's essentially organized around
the schema of ivy files and settings files, which is not the most
intuitive if you don't already know your way around the schema.  

I'm willing to contribute documentation myself, but IMO the current
process is just too cumbersome, i.e. check out the source, edit the file
(using xooki which has its own issues), create a patch, open a JIRA,
check in a patch, wait for the patch to be accepted or rejected.  I
would have submitted many documentation improvements already if it
weren't for this heavyweight process.

Documentation changes are low-risk, it makes no sense to protect it as
tightly as source code.  Maybe let's have a public documentation branch
where everyone can submit documentation, then a committer can review and
merge changes to the mainline as time permits.   

> -----Original Message-----
> From: Jean-Claude Cerebro [mailto:jeanclaude.cerebro@gmail.com] 
> Sent: Friday, April 11, 2008 1:16 PM
> To: ivy-user@ant.apache.org
> Subject: Re: documentation
> 
> 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
> >
> 

-----------------------------------------
====================================================
This message contains PRIVILEGED and CONFIDENTIAL
information that is intended only for use by the 
named recipient. If you are not the named recipient,
any disclosure, dissemination, or action based on 
the contents of this message is prohibited. In such
case please notify us and destroy and delete all 
copies of this transmission.  Thank you.
====================================================

Mime
View raw message