Return-Path: Delivered-To: apmail-ant-ivy-user-archive@www.apache.org Received: (qmail 77427 invoked from network); 11 Apr 2008 17:47:24 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 11 Apr 2008 17:47:24 -0000 Received: (qmail 63191 invoked by uid 500); 11 Apr 2008 17:47:22 -0000 Delivered-To: apmail-ant-ivy-user-archive@ant.apache.org Received: (qmail 63175 invoked by uid 500); 11 Apr 2008 17:47:22 -0000 Mailing-List: contact ivy-user-help@ant.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: ivy-user@ant.apache.org Delivered-To: mailing list ivy-user@ant.apache.org Received: (qmail 63136 invoked by uid 99); 11 Apr 2008 17:47:22 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 11 Apr 2008 10:47:22 -0700 X-ASF-Spam-Status: No, hits=-0.0 required=10.0 tests=SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: local policy) Received: from [69.25.87.29] (HELO compucredit.com) (69.25.87.29) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 11 Apr 2008 17:46:41 +0000 Received: from ([10.24.56.6]) by mail4.compucredit.com with ESMTP id 5503069.65437005; Fri, 11 Apr 2008 13:46:36 -0400 X-MimeOLE: Produced By Microsoft Exchange V6.5 Content-class: urn:content-classes:message MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Subject: RE: documentation Date: Fri, 11 Apr 2008 13:46:36 -0400 Message-ID: In-Reply-To: <957b91b30804111016m69186107s98bbf16c0f8cbd1d@mail.gmail.com> X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: documentation Thread-Index: Acib9+UmCtwuFi4vTQCiTHB96kgyWAAAYvGQ References: <957b91b30804091719x5ca91646wa2fad23933a7cf6d@mail.gmail.com> <635a05060804110432v77944c7am6668d4a72e5ff2f9@mail.gmail.com> <20080411115834.165310@gmx.net> <957b91b30804111016m69186107s98bbf16c0f8cbd1d@mail.gmail.com> From: "Brown, Carlton" To: Content-Type: text/plain; charset="us-ascii" X-Virus-Checked: Checked by ClamAV on apache.org I find the documentation is fairly complete in terms of content=2E It's=0D= =0Amuch better than some projects I could mention=2E However, in many plac= es=0D=0Ait lacks context and organization=2E It's essentially organized ar= ound=0D=0Athe schema of ivy files and settings files, which is not the most= =0D=0Aintuitive if you don't already know your way around the schema=2E = =0D=0A=0D=0AI'm willing to contribute documentation myself, but IMO the cur= rent=0D=0Aprocess is just too cumbersome, i=2Ee=2E check out the source, ed= it the file=0D=0A(using xooki which has its own issues), create a patch, op= en a JIRA,=0D=0Acheck in a patch, wait for the patch to be accepted or reje= cted=2E I=0D=0Awould have submitted many documentation improvements alread= y if it=0D=0Aweren't for this heavyweight process=2E=0D=0A=0D=0ADocumentati= on changes are low-risk, it makes no sense to protect it as=0D=0Atightly as= source code=2E Maybe let's have a public documentation branch=0D=0Awhere = everyone can submit documentation, then a committer can review and=0D=0Amer= ge changes to the mainline as time permits=2E =0D=0A=0D=0A> -----Original= Message-----=0D=0A> From: Jean-Claude Cerebro [mailto:jeanclaude=2Ecerebro= @gmail=2Ecom] =0D=0A> Sent: Friday, April 11, 2008 1:16 PM=0D=0A> To: ivy-u= ser@ant=2Eapache=2Eorg=0D=0A> Subject: Re: documentation=0D=0A> =0D=0A> Hel= lo Ivy Mailing List,=0D=0A> =0D=0A> Based on these responses my feeling is = that Xavier is taking =0D=0A> the brunt of the efforts for Ivy and that we = need to be more =0D=0A> collaborative in helping solve issues raised=2E=0D= =0A> =0D=0A> Looking at the emails it seems that Xavier has a great deal = =0D=0A> of domain-specific knowledge for ivy that needs to be =0D=0A> trans= lated into docs on the ivy web site=2E=0D=0A> =0D=0A> My suggestion is that= if we end up having issues solved from =0D=0A> the mailing list we transla= te them into docs on a ivy web site=2E=0D=0A> =0D=0A> For me, what's lackin= g is a use-case page because since Ivy =0D=0A> is so flexible without seein= g options and the ways people are =0D=0A> doing things, its hard for me to = know how best to use it=2E=0D=0A> =0D=0A> For example Shawn, looks like he = just spent six hours or so =0D=0A> trying to fix a cache problem that wasn'= t apparent from =0D=0A> reading the docs=2E Wouldn't this be a great thing= to put on =0D=0A> the docs in a more accessible way?=0D=0A> =0D=0A> As wel= l as the email with file extensions without artifacts?=0D=0A> =0D=0A> Jean-= Claude=0D=0A> =0D=0A> =0D=0A> On Fri, Apr 11, 2008 at 5:58 AM, Roman Legat = =0D=0A> wrote:=0D=0A> =0D=0A> > I'd like to menti= on on that:=0D=0A> >=0D=0A> > There is a lot of (good) documentation, which= is good =0D=0A> starting point=2E =0D=0A> > What could be reworked is the = structure=2E Sometimes it's =0D=0A> kind of hard =0D=0A> > to find the thin= gs you're looking for=2E=0D=0A> > What clearly is a mess right now is findi= ng the right documentation =0D=0A> > for the version you are using=2E In so= me places, the documentation is =0D=0A> > outdated, or tutorials are referr= ing to an older release=2E =0D=0A> The reason =0D=0A> > for this is that iv= y currently is in the process of =0D=0A> becoming 2=2E0=2E0 and =0D=0A> > m= igrating to apache=2E So we have to live with that for a while until =0D=0A= > > things become more stable=2E=0D=0A> >=0D=0A> > Nevertheless, it is up t= o every user to improve documentation, ivy =0D=0A> > even provides a rather= simple mechanism for changing and sending =0D=0A> > documentation diffs=2E= =0D=0A> > So, if you=0D=0A> > find a old reference, misspelling, outdated s= tuff - report it=2E That =0D=0A> > saves precious time for 2=2E0=2E0=2E=0D= =0A> >=0D=0A> > What I am missing are alternative writings on ivy/ivyde bes= ides the =0D=0A> > project documentation=2E Blogs, tutorial, stuff like tha= t from people =0D=0A> > using ivy=2E How are you using it? What are your pr= oblems, =0D=0A> how do you solve them?=0D=0A> > How do you setup your envir= onment?=0D=0A> >=0D=0A> > Roman=0D=0A> >=0D=0A> > -------- Original-Nachric= ht --------=0D=0A> > > Datum: Fri, 11 Apr 2008 13:32:49 +0200=0D=0A> > > Vo= n: "Xavier Hanin" =0D=0A> > > An: ivy-user@ant= =2Eapache=2Eorg=0D=0A> > > Betreff: Re: documentation=0D=0A> >=0D=0A> > > O= n Thu, Apr 10, 2008 at 2:19 AM, Jean-Claude Cerebro < =0D=0A> > > jeanclaud= e=2Ecerebro@gmail=2Ecom> wrote:=0D=0A> > >=0D=0A> > > > Hi Xavier,=0D=0A> >= >=0D=0A> > > Did you notice you sent this e-mail to a mailing list? =0D=0A= > Why am I the =0D=0A> > > only one to be fortunate enough to get your gree= tings ;-)=0D=0A> > >=0D=0A> > > >=0D=0A> > > > As a newbie just staring wit= h Ivy I must say that I =0D=0A> love Ivy but =0D=0A> > > > I'm disappointed= , not with the capability of Ivy but with the=0D=0A> > documentation=2E=0D= =0A> > > >=0D=0A> > > > Although the level of completeness is very detailed= , as a user=0D=0A> > > (customer)=0D=0A> > > > of=0D=0A> > > > Ivy I'm find= ing it very difficult to negotiate simple tasks =0D=0A> > > > without=0D=0A= > > > having=0D=0A> > > > to cross-references the examples, the docs, the w= ebsite, not so=0D=0A> > clearly=0D=0A> > > > defined links on the website, = and the faq=2E=0D=0A> > > >=0D=0A> > > > In addition, the docs on the websi= te although complete are not =0D=0A> > > > clear=0D=0A> > to=0D=0A> > > a= =0D=0A> > > > user=2E=0D=0A> > > >=0D=0A> > > > I feel that the adoption of= ivy in a larger scale =0D=0A> hinges on better =0D=0A> > > > documentation= =2E Documentation that is dead-simple and presents =0D=0A> > > > things=0D= =0A> > in=0D=0A> > > a=0D=0A> > > > use case fashion that builds on one ano= ther that tackles one =0D=0A> > > > concept=0D=0A> > at=0D=0A> > > a=0D=0A>= > > > time and then gets into the more complicated use cases=2E=0D=0A> > >= >=0D=0A> > > > Ivy is great and solves a problem really well, the =0D=0A> = documentation =0D=0A> > > > needs=0D=0A> > > to=0D=0A> > > > distill that i= n simplistic way=2E=0D=0A> > > >=0D=0A> > > > You may not agree and might b= e offended at this email and I =0D=0A> > > > apologize=0D=0A> > > for=0D=0A= > > > > that but I think someone needs to say this as I would =0D=0A> like = to see =0D=0A> > > > this project succeed and become widely adopted in the = industry=2E=0D=0A> > >=0D=0A> > > I'm not offended at all, it's always good= to get feedback =0D=0A> from the =0D=0A> > > community=2E Now about what I= think of the documentation: I =0D=0A> think most=0D=0A> > basic=0D=0A> > >= stuff is explained in tutorials, and should be able to =0D=0A> tackle simp= le =0D=0A> > > use cases after following the tutorials=2E Do you think =0D= =0A> tutorials are =0D=0A> > > not=0D=0A> > simple=0D=0A> > > enough?=0D=0A= > > >=0D=0A> > > Once you get the basic level from the tutorials, if you = =0D=0A> need to go =0D=0A> > > further, reference documentation should cont= ain answers to most =0D=0A> > > questions=2E I=0D=0A> > agree=0D=0A> > > it= 's not easy to find your way out of the doc, but it's =0D=0A> difficult to = =0D=0A> > > create simple guides or tutorials to every use case, Ivy is so = =0D=0A> > > flexible that=0D=0A> > you=0D=0A> > > can do many things we don= 't even always envision ourself=2E There's =0D=0A> > > also=0D=0A> > the=0D= =0A> > > mailing list which can be used to ask help from the =0D=0A> commun= ity=2E But =0D=0A> > > maybe you're thinking about one particular topic tha= t =0D=0A> would require =0D=0A> > > a guide or tutorial?=0D=0A> > >=0D=0A> = > > Lastly, this project is open, I don't know if you realize =0D=0A> the t= ime =0D=0A> > > Ivy committer team spend in developing Ivy? And answering = =0D=0A> questions? =0D=0A> > > And updating the reference documentation wit= h every =0D=0A> single change in =0D=0A> > > Ivy features? Maybe writing so= me more tutorials and introductory =0D=0A> > > material could deserve some = participation from users? from you?=0D=0A> > >=0D=0A> > > Xavier=0D=0A> > >= =0D=0A> > > >=0D=0A> > > >=0D=0A> > > > Jean-Claude=0D=0A> > > >=0D=0A> >= =0D=0A> > --=0D=0A> > Psst! Geheimtipp: Online Games kostenlos spielen bei = den =0D=0A> GMX Free Games!=0D=0A> > http://games=2Eentertainment=2Egmx=2En= et/de/entertainment/games/free=0D=0A> >=0D=0A> =0D=0A=0D=0A----------------= -------------------------=0D=0A=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0D=0AThis message contains PRIVILEG= ED and CONFIDENTIAL=0D=0Ainformation that is intended only for use by the = =0D=0Anamed recipient=2E If you are not the named recipient,=0D=0Aany discl= osure, dissemination, or action based on =0D=0Athe contents of this message= is prohibited=2E In such=0D=0Acase please notify us and destroy and delete= all =0D=0Acopies of this transmission=2E Thank you=2E=0D=0A=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D