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 -- <[EMAIL PROTECTED]> -- 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 994
