Le 11 avr. 08 à 20:17, Jean-Claude Cerebro a écrit :
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.
Well, per se a Jira issue is not required. It is just simpler for
tracking down patches.
Note also that if a wiki is setup I don't think the current reference
documentation will migrate to the wiki. The wiki would be an
additional documentation, with different rights management. So
changing the reference documentation will still need the patch process.
By the way, a user contributed documentation area is a good idea. At
Apache there is MoinMoin and Confluence available:
http://wiki.apache.org/general/
http://cwiki.apache.org/confluence/dashboard.action
Personally I do prefer Confluence.
Nicolas
On Fri, Apr 11, 2008 at 11:46 AM, Brown, Carlton <
[EMAIL PROTECTED]> 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:[EMAIL PROTECTED]
Sent: Friday, April 11, 2008 1:16 PM
To: [EMAIL PROTECTED]
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
<[EMAIL PROTECTED]> 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" <[EMAIL PROTECTED]>
An: [EMAIL PROTECTED]
Betreff: Re: documentation
On Thu, Apr 10, 2008 at 2:19 AM, Jean-Claude Cerebro <
[EMAIL PROTECTED]> 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.
====================================================
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
