Re: Word for the day: Undocumentation
Forgive me if I am looking in the wrong place for some of this stuff. I only started looking at this today. --- Michael Scott [EMAIL PROTECTED] wrote: I'm fine with that, I understand why - this is not a rant - but I do think that Parrot has a steep learning curve and that good documentation is essential if we want to lower it. The potential benefits seem obvious. I had a read through intro.pod (found a very minor error, patch submitted ) and decided that I might be able to write some tests but I am having a hell of a time trying to find out what tests have been written and which havn't. I have written a few _simple_ tests and deliberately broken a few others and I would like to write a few but I have no idea what needs doing. I have also been unable to find out if there is any sort of methodolgy to the testing. I have had a look through ./parrot/t/* and found a lot of test files but very little actual details on what each test was testing. I could infer from the code what most of the tests are trying to achieve but some docs would be nice. If there are more docs can someone point me at them (I have read most of ./parrot/docs/*.pod) and any other pod I have been able to find. After all that I suppose I should volunteer some time. I have some time on my hands at the moment and would like to get involved in some fashion. Unfortunately I am not a C guru but I am quite happy to write tests[0] in assembler or do documentation. In what areas do people think documentation or tests are most needed, I would be happy to start with the docs first until I am more comfortable with the code, ideas, advice? H [0] As soon as I am comfortable with the assembler, most of the easier tests seem to have been written. __ Do you Yahoo!? Protect your identity with Yahoo! Mail AddressGuard http://antispam.yahoo.com/whatsnewfree
Re: Word for the day: Undocumentation
Forgive me if I am looking in the wrong place for some of this stuff. I am quite new to this. --- Michael Scott [EMAIL PROTECTED] wrote: I'm fine with that, I understand why - this is not a rant - but I do think that Parrot has a steep learning curve and that good documentation is essential if we want to lower it. The potential benefits seem obvious. I had a read through the intro.pod and decided that I might be able to write some tests but I am having a hell of a time trying to find out what tests have been written and which ones have not. I have written a few _simple_ tests and deliberately broken a few others and I would like to contribute some but I have no idea what needs doing. I have also been unable to find out if there is any sort of methodolgy to the testing. I have had a look through ./parrot/t/* and found a lot of test files but very little actual details on what each test was testing. I could infer from the code what each test was trying to achieve but some docs would be nice. If there are more docs can someone point me at them (I have read most of ./parrot/docs/*.pod). After all that I suppose I should volunteer for something. I have some time on my hands at the moment and would like to get involved in some fashion. Unfortunately I am not a C guru but I am quite happy to write tests[0] in assembler or do documentation. In which areas do people think documentation or tests are most needed, I would be happy to start with the docs first until I am more comfortable with the code, ideas, advice? H [0] As soon as I am comfortable with the assembler, most of the easier tests seem to have been written. __ Do you Yahoo!? Protect your identity with Yahoo! Mail AddressGuard http://antispam.yahoo.com/whatsnewfree
Re: Word for the day: Undocumentation
On Fri, 14 Nov 2003, Harry Jackson wrote: I have also been unable to find out if there is any sort of methodolgy to the testing. I have had a look through ./parrot/t/* and found a lot of test files but very little actual details on what each test was testing. I could infer from the code what each test was trying to achieve but some docs would be nice. If there are more docs can someone point me at them (I have read most of ./parrot/docs/*.pod). Many of the tests in the t/ directory are there to test very specific, low-level things--making sure we can create a PMC of some particular type, or that an op works as documented. Some of the tests are a bit more elaborate, trying to exercise full subsystems, but for the most part we're making sure the tiny pieces work. (Which is good, as the big bits can't work if the little ones don't) We still don't cover all the extant op variants, and we could certainly use larger and more abusive tests, so anything you're interested in writing would be much appreciated. Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Word for the day: Undocumentation
Just a reminder for new checkins. Please make sure there is a minimum of a header comment for each routine you checkin describing just what the heck the routine does. Debugging certain parts of Parrot has become akin to mapping out a rabbit hole using marking flares. For example, just picking a random file (ok not really so random...) which will remain nameless to protect the innocent, with a 20 second search I locate blocks of 129 and 112 consecutive lines with no comments. Not that comments have to be an exact ratio but ours is approaching 1 percent. I think overall there is just too much undocumentation going on. :) Cheers, -Melvin
Re: Word for the day: Undocumentation
snip ...too much undocumentation going on. One of the reasons I started putting stuff on the wiki was because I could see that updating documentation was not a high priority. On the wiki I neither have to have CVS checkin rights, nor do I have to wait for someone with those rights to act upon what I suggest. This has led to my own parallel documentation - I even document the state of the documentation. I know what I have put together is incomplete and inadequate, but do I move it forward, and I keep it up to date. When it comes to pointing out that parrot_assembly.pod is just an earlier version of PDD 6, or that the Per-entity comments section in PDD 7 needs some thought, or that a submissions.pod should be added, I get warnocked. I'm fine with that, I understand why - this is not a rant - but I do think that Parrot has a steep learning curve and that good documentation is essential if we want to lower it. The potential benefits seem obvious. I'd like to volunteer myself as official Parrot documentation person - a semi-autonomous process with clearly defined protocols and goals - and the necessary rights to achieve them. I'm happy to expand on what I mean by that - if I get a response. Mike
Re: Word for the day: Undocumentation
On Thu, 13 Nov 2003, Michael Scott wrote: I'd like to volunteer myself as official Parrot documentation person - a semi-autonomous process with clearly defined protocols and goals - and the necessary rights to achieve them. I'm happy to expand on what I mean by that - if I get a response. If you're willing, fine with me. Get yourself an account on perl.org and mail me the name and we'll get you CVS checkin privs. And we can discuss what you've got in mind. Dan --it's like this--- Dan Sugalski even samurai [EMAIL PROTECTED] have teddy bears and even teddy bears get drunk
Re: Word for the day: Undocumentation
At 08:10 PM 11/13/2003 +0100, Michael Scott wrote: snip ...too much undocumentation going on. One of the reasons I started putting stuff on the wiki was because I could see that updating documentation was not a high priority. On the wiki I neither have to have CVS checkin rights, nor do I have to wait for someone with those rights to act upon what I suggest. This has led to my own parallel documentation - I even document the state of the documentation. I know what I have put together is incomplete and inadequate, but do I move it forward, and I keep it up to date. I've used the wiki quite a few times lately. It is great. When it comes to pointing out that parrot_assembly.pod is just an earlier version of PDD 6, or that the Per-entity comments section in PDD 7 needs some thought, or that a submissions.pod should be added, I get warnocked. That will keep happening until our number of active, core developers grows beyond its current number of 4-5. Also, a couple of the guys split time between Parrot and P5 so its worse. I'd like to volunteer myself as official Parrot documentation person - a semi-autonomous process with clearly defined protocols and goals - and the necessary rights to achieve them. Would commit privs to the docs directories help, for a start? -Melvin
