You know what? There is nothing like "official" information. If you start off doing the doc on the wiki, and it gets better than the one on the webpage (and trust me, I will add a link to the corresponding wiki pages from the component pages to ensure competitition is fair); your doc will grow to be official.
Why don't we start an official doc competition? Ready - steady - go! and after some time, we can reevaluate the approaches.... Have fun documenting on the WIKI! regards, Martin On 8/26/05, ir. ing. Jan Dockx <[EMAIL PROTECTED]> wrote: > Trust me, I love the work you're doing. And I don't want to make > enemies. > > Sadly, the response you sent confirms my analysis: you are very, very > busy after hours making great code for MyFaces, and you have no time to > spent on the documentation 'right now'. That next version needs > shipping. You're being bugged by users on the mailing list that really > need it, and you want to oblige. Furthermore, from looking at the > history of the project, it is clear that the committers don't really > have a "natural drive" towards user documentation. Now, that is not a > complaint, that is not a reproach, it's however a fact. You're not > alone in those dire straits, BTW ;-). But the fact remains that user > documentation is not a priority for you, since the committers know the > code from the inside, and don't have this itch: you don't need user > documentation yourself. > > All this together makes that we will not have even mediocre user > documentation for a while. That's a problem for your users. What I am > suggesting is that you prioritize, and put the "svn / forrest > documentation" on hold for now. Stabilize the code, and get that next > version out! What you like to do, what you want to do, and what you are > good at. In the mean while, lower the bar for users to scratch their > itch, and motivate them to solve their own problem, and leave you to > focus at the code. Yes, for users it is "too" hard to write forrest > documentation. I work with a bunch of them. Seriously. Promote the wiki > to "official documentation at interim", and plan to move it to the svn > / forrest documentation format "at a later time", and respond to all > emails with "if you solved your issue, and you understand the component > a bit better now, please report your findings in the wiki; it's 10 > minutes work". "At a later time", you will find an almost finished > documentation set, you can work into the format you require. But I > strongly believe that for that to succeed, > 1) the bar needs to be extremely low for users > 2) it needs to be 'official' (be it at interim) > 3) new users need to be pointed to the 'growing documentation', > directly, it can't be second tier (be it at interim) > 4) and they need to be reminded constantly that they can easily > contribute (mailing list) > > Sorry, couldn't resist on making my point. I hope I convinced the > committers, but I'll leave it at this. I'm going to bed now ;-). > > > > On 26 Aug 2005, at 0:17, Sean Schofield wrote: > > > It's not too hard to write forrest documentation. It takes a little > > bit of effort and if you or any other user does not want to put forth > > that effort then fine. As for your lack of interest in creating svn > > patches ... well that is how things are done at the ASF. The project > > is not a giant free-for-all like a wiki is. > > > > We rely on our users to help us. There are many ways to help. The > > most important is this mailing list. Users helping other users. If > > you have something you want to share with other users then the wiki is > > fine. > > > > Nobody is afraid of wikis and if you look at what I said in my earlier > > post, I gave several examples of where wiki's are appropriate. In > > fact, I am the one who added a link to the wiki from our website and I > > made several updates to the wiki (for project management stuff) just > > yesterday. > > > > The tomahawk documentation is a key part of the MyFaces project that > > is every bit as important as the source code. So therefore we have > > chosen to put the same restrictions on this documentation as we do the > > source code. Yes that slows things down but you are focusing on the > > down-side. It also keeps things under control and useable. > > > > Again I refer you to other ASF projects (commons, ant, struts, etc.) > > Some have wikis but the key documentation on how to use the product is > > part of svn and under control of the PMC and committers. Sorry, > > that's just how ASF works. > > > > We're happy to accept consider any of your suggestions/contributions. > > If you would like to limit your contributions to mailing list > > participation and/or wiki documentation we welcome your help. > > > > I agree that there is a lack of documentation. We are working on it. > > We all have day jobs and things on this project are moving incredibly > > fast. Please bear with us or better yet, help us in the way we most > > need help (xdocs and svn patches.) > > > > sean > > > > > >> I'm not saying *I* am not writing doc's on the wiki. I am saying that > >> with these rules, there won't be a giant, inspired, communal effort to > >> create the docs. I *am* saying that I will not be submitting patches > >> for documentation, and that I suspect nobody will, because of the > >> large > >> effort this requires, in contrast to editing a wiki. And with this > >> setup, that effort (during a development project at your day time job, > >> with an undoubtedly impossible deadline) doesn't weigh against the > >> eeny > >> weeny gain in your noösphere ;-). Like all OSS, it's about scratching > >> your own itch. People are simply not inclined to work on make-believe > >> material, and right now the wiki is playing house, not the 'real' > >> stuff. Imagine the people at WikiPedia saying "yeah, yeah, but what > >> you > >> type here is not interesting, not 'real', you should see the 'real' > >> stuff we do". > > > >> And with what I am seeing on progress you make on the code, the pain > >> it > >> takes to get to a next stable version, and the effort that goes in > >> there (see the masses of communication on the mailing list and in the > >> JIRA), I believe the project people (kudo's) won't have the time to > >> copy doc's to svn. Let's be honest: this hasn't been a serious > >> consideration in the past. Yes, this is a note of critique: this > >> project is seriously under-documented (not only in the user doc's, but > >> also in the source code, BTW). > >> > >> So, by combining these opinions, I come to the conclusion that there > >> will be no, not even mediocre, evolving, user documentation in the > >> foreseeable future. Like I said: bummer. > >> > >> Frankly, this discussion (I really didn't intend on starting, but it's > >> a slow night here ;-)) reminds me a bit of the discussion 2 months ago > >> about using maven or not. It is clear that the project leaders are not > >> comfortable, in this case, with the basic idea of wiki. We have a > >> different opinion on that (I have enormously positive experiences with > >> wiki's), and that's ok. Still kudo's and muchas gracias for the > >> MyFaces > >> effort. > >> > >> > >> On 25 Aug 2005, at 22:47, Mike Kienenberger wrote: > >> > >>> No one is saying that you shouldn't write the docs on the wiki. > >>> They're just saying that the "official" version of the documentation > >>> is in svn, and that documentation in the wiki eventually needs to be > >>> ported over to the website, and that submitting a patch to do so make > >>> the process go faster. > >>> > >>> In my opinion, this is the correct choice. The website/xml docs are > >>> something that can be distributed and used without an internet > >>> connection, while the wiki requires an active internet connection. > >>> > >>> -Mike > >>> > >>> On 8/25/05, ir. ing. Jan Dockx <[EMAIL PROTECTED]> wrote: > >>>> You obviously have a lot of time at your disposal ;-). But hey, it's > >>>> you project. I was writing some doc's on the wiki right now, but I > >>>> am > >>>> not going to go through the hassle of creating patches and stuff. > >>>> You > >>>> obviously want tight control, and you're welcome to that, of course. > >>>> Sadly, that means no doc's by Monday, created by a giant, > >>>> well-willing, > >>>> communal user effort. ;-). Bummer. > >>>> > >>>> On 25 Aug 2005, at 21:08, Sean Schofield wrote: > >>>> > >>>>> I disagree with moving stuff from the website to the wiki. I think > >>>>> the component doc should go on the website and be part of the > >>>>> official > >>>>> MyFaces svn. This will also ensure uniform standards and quality > >>>>> of > >>>>> the doc. > >>>>> > >>>>> If users want to put extra component doc in the wiki (or are not > >>>>> comfortable with Forrest or subversion) then as Martin said, this > >>>>> will > >>>>> be a small help b/c eventually we can move it. > >>>>> > >>>>> IMO wiki is also a good candidate for server configuration, IDE > >>>>> configuration, etc. Additional examples are also fine for wiki. > >>>>> But > >>>>> documentation on the components should be on the website. That's > >>>>> what > >>>>> is expected. Check out the Ant project. You will see all of the > >>>>> tasks documented right there (no wiki.) > >>>>> > >>>>> sean > >>>>> > >>>>> On 8/25/05, ir. ing. Jan Dockx <[EMAIL PROTECTED]> wrote: > >>>>>> Well, -1 on that, actually. I am a great believer in wiki's, and I > >>>>>> suggest that you won't copy the doc to the homepage, but link from > >>>>>> the > >>>>>> homepage to the wiki. One of the stifling things about the MyFaces > >>>>>> documentation is that it is in Too Many Places. Nobody knows where > >>>>>> to > >>>>>> look exactly, people are not eager to work on doc's that are not > >>>>>> the > >>>>>> reals doc's, and create patches and submit them and stuff is far > >>>>>> to > >>>>>> time consuming. For writing doc's in the wiki, you don't need to > >>>>>> checkout the source tree. This is enduser documentation, not > >>>>>> developer > >>>>>> documentation, so the overhead is stifling the work. > >>>>>> > >>>>>> I suggest "we" decide that the documentation will be the wiki. > >>>>>> Let's > >>>>>> move whatever there is in /forest/content to the wiki (users can > >>>>>> do > >>>>>> that), and kill that part it Subversion. The examples should stay. > >>>>>> At > >>>>>> a > >>>>>> (much) later date, somebody could decide to create a pdf or a book > >>>>>> based on the wiki, but that's another story, and not our current > >>>>>> concern. > >>>>>> > >>>>>> > >>>>>> On 25 Aug 2005, at 16:29, Martin Marinschek wrote: > >>>>>> > >>>>>>> +1 > >>>>>>> > >>>>>>> ;) > >>>>>>> > >>>>>>> If you want to get involved even more, it would be great if you > >>>>>>> would > >>>>>>> add this documentation to the /forrest/content section of our > >>>>>>> sourcetree for viewing it on the homepage. > >>>>>>> > >>>>>>> (just send us patches, we will commit them) > >>>>>>> > >>>>>>> If not, just put it on the WIKI, and gradually we will move it > >>>>>>> over > >>>>>>> to > >>>>>>> the homepage. > >>>>>>> > >>>>>>> regards, > >>>>>>> > >>>>>>> Martin > >>>>>>> > >>>>>>> On 8/25/05, Clément Maignien <[EMAIL PROTECTED]> > >>>>>>> wrote: > >>>>>>>> > >>>>>>>> +1 > >>>>>>>> > >>>>>>>> > >>>>>>>> -----Message d'origine----- > >>>>>>>> De : ir. ing. Jan Dockx [mailto:[EMAIL PROTECTED] > >>>>>>>> Envoyé : jeudi 25 août 2005 16:16 > >>>>>>>> À : MyFaces Discussion > >>>>>>>> Objet : Let's write that doc! > >>>>>>>> > >>>>>>>> I suggest that we make this a user effort. Everybody, make an > >>>>>>>> account > >>>>>>>> in the > >>>>>>>> wiki, and <a > >>>>>>>> href="http://wiki.apache.org/myfaces/MyFacesComponents";>let's > >>>>>>>> start documenting those components</a>. If everybody writes a > >>>>>>>> little > >>>>>>>> piece > >>>>>>>> (what is it for, how to use it), we'll have full documentation > >>>>>>>> by > >>>>>>>> Monday. > >>>>>>>> > >>>>>>>> I just added a little grain. More to come, I promise. > >>>>>>>> > >>>>>>>> > >>>>>>>> On 25 Aug 2005, at 15:30, Sean Schofield wrote: > >>>>>>>> > >>>>>>>> > >>>>>>>> > >>>>>>>> Thanks so much for pointing out that messages tag. I was just > >>>>>>>> about > >>>>>>>> to write something similar because I didn't know about it. Is it > >>>>>>>> listed somewhere on the MyFaces website? I don't see it here: > >>>>>>>> http://myfaces.apache.org/tomahawk/overview.html > >>>>>>>> > >>>>>>>> Unfortunately that page is woefully out of date. Updating it is > >>>>>>>> on > >>>>>>>> my > >>>>>>>> shortlist of things to do. > >>>>>>>> > >>>>>>>> > >>>>>>>> Regarding your comment on it being specific to MyFaces: Isn't it > >>>>>>>> only > >>>>>>>> specific to the MyFaces extensions? In other words, couldn't I > >>>>>>>> use > >>>>>>>> it > >>>>>>>> with the RI as long as I included the > >>>>>>>> myfaces-extensions-1.0.9.jar > >>>>>>>> and > >>>>>>>> referenced the taglib? > >>>>>>>> > >>>>>>>> Right you can use tomahawk with the RI and if you want that > >>>>>>>> functionality use <t:message> instead of <h:message>. > >>>>>>>> > >>>>>>>> > >>>>>>>> -Ken > >>>>>>>> > >>>>>>>> sean > >>>>>>>> > >>>>>>>> > >>>>>>>> Met vriendelijke groeten, > >>>>>>>> > >>>>>>>> Jan Dockx > >>>>>>>> > >>>>>>>> PeopleWare NV - Head Office > >>>>>>>> Cdt.Weynsstraat 85 > >>>>>>>> B-2660 Hoboken > >>>>>>>> Tel: +32 3 448.33.38 > >>>>>>>> Fax: +32 3 448.32.66 > >>>>>>>> > >>>>>>>> PeopleWare NV - Branch Office Geel > >>>>>>>> Kleinhoefstraat 5 > >>>>>>>> B-2440 Geel > >>>>>>>> Tel: +32 14 57.00.90 > >>>>>>>> Fax: +32 14 58.13.25 > >>>>>>>> > >>>>>>>> http://www.peopleware.be/ > >>>>>>>> http://www.mobileware.be/ > >>>>>>>> > >>>>>>> > >>>>>>> > >>>>>>> -- > >>>>>>> > >>>>>>> http://www.irian.at > >>>>>>> Your JSF powerhouse - > >>>>>>> JSF Trainings in English and German > >>>>>>> > >>>>>>> > >>>>>> Met vriendelijke groeten, > >>>>>> > >>>>>> Jan Dockx > >>>>>> > >>>>>> PeopleWare NV - Head Office > >>>>>> Cdt.Weynsstraat 85 > >>>>>> B-2660 Hoboken > >>>>>> Tel: +32 3 448.33.38 > >>>>>> Fax: +32 3 448.32.66 > >>>>>> > >>>>>> PeopleWare NV - Branch Office Geel > >>>>>> Kleinhoefstraat 5 > >>>>>> B-2440 Geel > >>>>>> Tel: +32 14 57.00.90 > >>>>>> Fax: +32 14 58.13.25 > >>>>>> > >>>>>> http://www.peopleware.be/ > >>>>>> http://www.mobileware.be/ > >>>>>> > >>>>>> > >>>>>> > >>>>> > >>>>> > >>>> Met vriendelijke groeten, > >>>> > >>>> Jan Dockx > >>>> > >>>> PeopleWare NV - Head Office > >>>> Cdt.Weynsstraat 85 > >>>> B-2660 Hoboken > >>>> Tel: +32 3 448.33.38 > >>>> Fax: +32 3 448.32.66 > >>>> > >>>> PeopleWare NV - Branch Office Geel > >>>> Kleinhoefstraat 5 > >>>> B-2440 Geel > >>>> Tel: +32 14 57.00.90 > >>>> Fax: +32 14 58.13.25 > >>>> > >>>> http://www.peopleware.be/ > >>>> http://www.mobileware.be/ > >>>> > >>>> > >>>> > >>> > >>> > >> Met vriendelijke groeten, > >> > >> Jan Dockx > >> > >> PeopleWare NV - Head Office > >> Cdt.Weynsstraat 85 > >> B-2660 Hoboken > >> Tel: +32 3 448.33.38 > >> Fax: +32 3 448.32.66 > >> > >> PeopleWare NV - Branch Office Geel > >> Kleinhoefstraat 5 > >> B-2440 Geel > >> Tel: +32 14 57.00.90 > >> Fax: +32 14 58.13.25 > >> > >> http://www.peopleware.be/ > >> http://www.mobileware.be/ > >> > >> > >> > > > > > Met vriendelijke groeten, > > Jan Dockx > > PeopleWare NV - Head Office > Cdt.Weynsstraat 85 > B-2660 Hoboken > Tel: +32 3 448.33.38 > Fax: +32 3 448.32.66 > > PeopleWare NV - Branch Office Geel > Kleinhoefstraat 5 > B-2440 Geel > Tel: +32 14 57.00.90 > Fax: +32 14 58.13.25 > > http://www.peopleware.be/ > http://www.mobileware.be/ > > > -- http://www.irian.at Your JSF powerhouse - JSF Trainings in English and German
