From ivy-user-return-3023-apmail-ant-ivy-user-archive=ant.apache.org@ant.apache.org Fri Apr 11 18:17:45 2008 Return-Path: Delivered-To: apmail-ant-ivy-user-archive@www.apache.org Received: (qmail 92948 invoked from network); 11 Apr 2008 18:17:45 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 11 Apr 2008 18:17:45 -0000 Received: (qmail 17519 invoked by uid 500); 11 Apr 2008 18:17:45 -0000 Delivered-To: apmail-ant-ivy-user-archive@ant.apache.org Received: (qmail 17470 invoked by uid 500); 11 Apr 2008 18:17:45 -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 17461 invoked by uid 99); 11 Apr 2008 18:17:45 -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 11:17:45 -0700 X-ASF-Spam-Status: No, hits=2.0 required=10.0 tests=HTML_MESSAGE,SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: domain of jeanclaude.cerebro@gmail.com designates 209.85.162.183 as permitted sender) Received: from [209.85.162.183] (HELO el-out-1112.google.com) (209.85.162.183) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 11 Apr 2008 18:17:04 +0000 Received: by el-out-1112.google.com with SMTP id r23so652900elf.22 for ; Fri, 11 Apr 2008 11:17:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:received:received:message-id:date:from:to:subject:in-reply-to:mime-version:content-type:references; bh=/ZRYDxeRzzhF0W/wZ1/qBi3MQ50zzhZ680eo+d1fRjA=; b=xrCWw8L9zBwfTQ2LP+4Mh6/W4BOIW0z+G7zvjfS7eHj56oTYrIvGn6WTX93bfXB1kpi8U0WNrpZa3fHJTgre8JqMIDerBr+xhxDSdeeSdYR9/fSvK4p+Ti10A0s8dbT+epNXJWUpWj9ahFQ/VeyCVxYCqqMX26UsQ2I3N5MhcHg= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=message-id:date:from:to:subject:in-reply-to:mime-version:content-type:references; b=bI4ng0kRs+qMZTI7uKxI//4GBderGFm7oWiu2kiz/GIMr3vRJXoC2857OnH4v5mlRRGz0NIR/ee1uUl9tran37EByGjGz6BfSFNiAF2byzaBAV/GB39tk3WxoczphffXT+m4oLsbJEYZL8nlzwRWywC4ggj3jORkIfOXQOxiQ8Y= Received: by 10.141.28.12 with SMTP id f12mr1716351rvj.1.1207937834779; Fri, 11 Apr 2008 11:17:14 -0700 (PDT) Received: by 10.141.76.9 with HTTP; Fri, 11 Apr 2008 11:17:14 -0700 (PDT) Message-ID: <957b91b30804111117h2683830ftb433fe49968c8b69@mail.gmail.com> Date: Fri, 11 Apr 2008 12:17:14 -0600 From: "Jean-Claude Cerebro" To: ivy-user@ant.apache.org Subject: Re: documentation In-Reply-To: MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----=_Part_24550_18198202.1207937834765" References: <957b91b30804091719x5ca91646wa2fad23933a7cf6d@mail.gmail.com> <635a05060804110432v77944c7am6668d4a72e5ff2f9@mail.gmail.com> <20080411115834.165310@gmx.net> <957b91b30804111016m69186107s98bbf16c0f8cbd1d@mail.gmail.com> X-Virus-Checked: Checked by ClamAV on apache.org ------=_Part_24550_18198202.1207937834765 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline I agree. In this case then, I would suggest we get a wiki that we can freely edit and the core ivyteam can pick and choose what they want to include into the main docs. Confluence is a great option and codehaus uses this. I didn't realize the process involved a JIRA issue. If that's the case then that acts as a deterrent to update docs in my opinion. On Fri, Apr 11, 2008 at 11:46 AM, Brown, Carlton < Carlton.Brown@compucredit.com> wrote: > 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 > > 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" > > > > 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. > ==================================================== > ------=_Part_24550_18198202.1207937834765--