>Let's look at it this way, most projects are self-documenting. How? The >mailing list. The vast majority of really good Avalon documentation is in >the mailing list. When I have a question about how to use some other open >source project, the first place I'll turn after the main web site is the >mail list archive.
>Trouble is, mailing list archives aren't an effective way to document a >project. It isn't user friendly. Solution? Wiki. Make it a practice >whenever someone answers a question on the mailing list to include it in >the >wiki. The wiki allows anyone to document (don't have to have CVS commit >karma) and shows up right away. >The hard part to wiki's is keeping them organized. They get cluttered >easily. But as long as one or two people are willing to monitor the wiki >and clean up the mess now and then, it works very well. I don't know too much abt wikis etc but I think pointing a beginner to the mailing list archive is not so good. You could very easily get lost. And I use ant, maven, torque etc but I don't even know where their wikis are located. The point is the main website of the project is the "chief" source where people look for information. In my opinion that information on the websites is what has made projects like Ant, Struts etc so popular. And making html webpages out of information is not a big deal. Give me the information and I"ll make the webpages. I think it is wrong to assume that people would take wikis very seriously, typical mentality is to look for information on the website. If making the wiki is first step towards making the complete website then it is ok though. Vikas -----Original Message----- From: Farr, Aaron [mailto:[EMAIL PROTECTED] Sent: Tuesday, March 02, 2004 9:59 AM To: 'Avalon framework users' Subject: RE: PowerPoint presentation > -----Original Message----- > From: Niclas Hedhman [mailto:[EMAIL PROTECTED] > > On Wednesday 03 March 2004 01:16, Pawel X Karendys wrote: > > You can > > NOT expect newcomers to start writing a lot of documentation without > > knowing well a fairly large framework like Avalon, this approach will > add > > even more to the existing confusion around this project. > > I AM very well aware of this. As I said, the trick is how to make > "documentation more central" to project development. I think the trick to three fold: 1. wiki 2. Unit Tests 3. Javadocs Let's look at it this way, most projects are self-documenting. How? The mailing list. The vast majority of really good Avalon documentation is in the mailing list. When I have a question about how to use some other open source project, the first place I'll turn after the main web site is the mail list archive. Trouble is, mailing list archives aren't an effective way to document a project. It isn't user friendly. Solution? Wiki. Make it a practice whenever someone answers a question on the mailing list to include it in the wiki. The wiki allows anyone to document (don't have to have CVS commit karma) and shows up right away. The hard part to wiki's is keeping them organized. They get cluttered easily. But as long as one or two people are willing to monitor the wiki and clean up the mess now and then, it works very well. Unit tests make excellent short little examples and tutorials, especially if they have inline code documentation. And besides, we should be doing them anyway. The only missing part here is something that incorporates the unit tests into the documentation better, thus encouraging users to look to the unit tests for examples (most users won't do this). Now, about Javadocs. Well, we have to write the code anyway. If developers aren't interested in writing long tutorials and examples, javadocs at least give users something to work with. This also follows the whole "code/project documents itself theme." So that's going to be my approach. I'm starting with the wiki. I'll then move to provide more unit tests and javadocs. If anyone has a better idea, I'd love to know. > Aaron is working really hard to fill endless holes. I sometimes feel bad that it's been so long since I contributed much actual code. There's a couple of things that I've been meaning to get to, but the documentation means a lot to me. It's something I'm willing to do and want to see happen. > As for putting the PP on the Avalon site, I think it is just a matter of > committing it into CVS and update the site. I doubt there is any need for > legal procedure... If no one gets to it before me, I'll add it to CVS and put a link on the documentation page (http://avalon.apache.org/docs) J. Aaron Farr SONY ELECTRONICS DDP-CIM (724) 696-7653 --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
