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 < [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. > ==================================================== >
