[rfc-i] RFC Style guide
paul.hoffman at vpnc.org
Fri Jan 28 09:38:12 PST 2011
On 1/28/11 9:08 AM, Glenn Kowack wrote:
> On Jan 27, 2011, at 5:00 PM, Bob Brade wrote:
>> On 1/19/2011 12:06 PM, Glenn Kowack wrote:
>>> revising, reorganizing, and updating the Style Guide (along with the Procedures
>>> Manual) is called out as a priority in the TRSE (transitional RFC Series Editor)
>>> recommendations. I also call out that 1) I'd like to see greater participation by
>>> the community in creating the style guide and 2) it may be useful to have two
>>> parts to the style guide: a) consisting of a small set of 'musts' that are enforced
>>> by the Editorial (RPC) staff, and b) a large set of guidelines, examples, and
>> Regarding the RFC Editor as of a year ago (I have not looked at it since), it did attempt to make clear what were requirements and what were recommendations. Making it two separate documents seems to me not only overkill but also creating undesirable rigidity.
> Noted. Any split would have to be well-motivated, for exactly the reasons you state.
> The arguments I've heard include that the 'MUSTs' (2a) above would change very
> slowly, and (2b) above could be added to regularly. Having two parts of the guide
> with very different rhythms could potentially justify separate docs. I think this will
> all come out in the wash when people dive into the actual work.
A different method, one that would be easier to implement, would be an
RFC with the complete list that states up front "there may be updates;
see <specific url> for any differences". This setup has been pretty
standard in the technical book publishing business for over a decade. It
also makes it more like our current errata process, except that the
place where the changes might happen is called out in the document.
>>> The former will be very slow in changing and intentionally
>>> small; the latter will probably change with greater frequency and have more
>>> active community participation in its creation than would (a).
>>> Publishing the Style Guide as an RFC is an excellent idea. I'd like to see a
>>> discussion about that here, starting with:
>>> - why should the Style Guide be an RFC?
>>> - are there any reasons why the Style Guide should not be?
>> Yes, there are (or were) reasons, else the former RSE would have published it as an RFC. The style guidelines were changing fairly rapidly, so we decided that the Style Guide should be a "living document" for ease of maintenance and currency. And the RFC Editor could not reasonably be accused of opposing use of the RFC process.
>> Perhaps the style has stabilized since then, which might weaken this argument for the future.
> See note above: division might support this as well.
>> It has always been readily and immediately available ('one click away") on the RFC Editor web site. Why isn't a URL good enough in today's world?
> Some of the things I heard from community members is that the style guide
> has various part under multiple URLs. There's also the issue of persistence
> of reference. Some think URLs less stable (rightly or wrongly). Some want
> a more fixed object to refer to, and being part of an archival series would
> certainly do that.
A URL whose host is "www.rfc-editor.org" should be considered stable by
everyone. If such a URL is unstable, that is a serious management
problem that can, fortunately, easily be fixed. This is not to say that
the style guide should never be an RFC, simply that it can also reside
at a stable URL as well.
More information about the rfc-interest