Front page | perl.bootstrap |
Postings from August 2000
Last night we had a Melbourne.pm dinner and we were, of course, discussing Perl 6 and the language RFCs. Something that became apparent was that the RFCs are a tad confusing, and we came up with some things which we thought might help. Firstly, an RFC should usually only address one point. Some existing RFCs address two or more issues in one RFC, and this can cause confusion. An example (which I choose only because it's recent) is RFC 103, 'Fix print "$r->func" and $pkg::$var precedence', which should probably be two separate RFCs. So, if you have an RFC which addresses multiple concepts, it would be good if you could split them out. The exception to this is what we called an "approach" RFC, where a single RFC is a sort of umbrella document explaining a way to approach a collection of issues, and spawns related RFCs to talk about each individual part of the approach. An example might be Uri's broad I/O RFC (47), which touches on a range of related areas. If you're going to write an "approach" RFC, it would be good to try and make it clear that you're doing so. Ways of doing this include explicitly saying so in the abstract, referring heaps to the detailed RFCs, and pointing out in discussions of the RFC that it only discusses the broad approach to the issue and that finicky implementation details are better discussed in the context of the detailed RFCs. Another thing I wanted to touch on was RFC titles. It would help heaps if people gave RFCs titles which make as much sense as possible to people skimming the RFC index at http://dev.perl.org/rfc/. This means making the title sufficiently detailed to distinguish it from other RFCs, and ensuring that it contains enough information for people to get some idea of what you're proposing. A good idea is to put "X should Y" or "X should not Y" so that we know whether you're in favour of something or against it. Just looking at the RFC index, those with verbs in the name are generally clearer; for instance, compare "Eliminate bareword filehandles" (33) with "print operator" (39) (again, not picking on the authors of any particular RFCs, these ones just happen to be on the page in front of me). I hope my rambling is reasonably clear. I'm not intending to lay down excessively restrictive rules on writing RFCs, but just to suggest some hints that people might like to consider when drafting them. Comments welcome. K. -- Kirrily Robert -- <skud@netizen.com.au> -- http://netizen.com.au/ Open Source development, consulting and solutions Level 10, 500 Collins St, Melbourne VIC 3000 Phone: +61 3 9614 0949 Fax: +61 3 9614 0948 Mobile: +61 410 664 994Thread Next