Re: documentation

[Nicolas Lalevée <ni...@hibnet.org>]

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 <
> 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
>>> <ro...@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" <xa...@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.
>> ====================================================
>>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org