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 18:17:14 GMT
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
> > <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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message