Here's a draft of my Promotorial style guide. I'd appreciate comments.
It's written in my characteristic verbose style. I'm happy to
formulate a condensed version if people agree with the idea, but would
prefer something they can read more quickly.
-Aris
---
OFFICE OF THE PROMOTOR: OFFICIAL STYLE GUIDE
This document contains the Promotorial style guide, telling you how the
Office of the Promotor would prefer for you to format proposals. This
guide is non-binding, and I can fix most lapses (that's my job). Still,
I'd really appreciate it if you'd give it a read through and maybe consider
applying it next time you write a proposal. Some of the things that I'd like
you to do might actually slightly reduce the work you have to do. I'm more
than happy to answer questions if you have any. I really appreciate you taking
the time to read this.
Lines are wrapped to 80 characters. I don't mind wrapping them myself,
although it's a tad annoying when someone composes a proposal entirely
in eir email client and the lines aren't wrapped at all, forming giant
paragraphs all one one line. I don't mind if you wrap yourself to fewer than
80 characters: I'll probably just leave it with your wrapping. However,
making it so I can't wrap lines is VERY STRONGLY DISCOURAGED. This means
things like a quotation mechanism that marks each quoted line, or line
comments that aren't very short. PLEASE do not stop me from wrapping lines
consistently. Just about the only exception to this rule is URLs that are
over the limit, which I'll leave unwrapped.
Titles should be fairly short. I'm not picky about this, but if your title
is much over 40 characters I'll probably get annoyed with you. People sometimes
come up with 100+ character titles; that sort of thing is VERY STRONGLY
DISCOURAGED. Additionally, if you submit multiple versions of a proposal,
you're ENCOURAGED to each successive version with versions in the form "v2",
"v3", etc., but STRONGLY DISCOURAGED from marking versions in ways that differ
substantially from that.
Intents are two spaces per indent level. I don't mind fixing this for you at
all, but if you're ever wondering what to use, use two spaces. Also, if
there's a numbered or bulleted list, it's the number or bullet that gets
aligned to two spaces, and then all of the text lines up.
Headers should preferably be as close as possible to the heading used
for distributions, which looks like this:
Title: _
Adoption index: _._
Author:
Co-authors: ,
The closer than you can get to that, the more helpful it is. That includes
putting things in that order, writing out all the fields, even the ones
that have default values, and writing each field on its own line. I can deal
with other formats, but I'll smile (literally) if you use this one.
Also, marking your proposal text with "text:" is STRONGLY DISCOURAGED.
It doesn't help and it makes it more annoying to copy-paste. If you'd like
extra bonus points, you can mark the proposal text in curly brackets or
a line composed of all one character (like "--" or "//"). However,
it is STRONGLY DISCOURAGED to use any marking *on the same line* as the proposal
text. The proposal text should begin and end on a newline, with no characters
that aren't part of the text on the same line.
Again, thank you for reading this. This guide is non-binding, but if you could
try to follow it as much as conveniently possible, it would make my life
simpler. It is the Promotor's job to format the proposals, and dealing with
irregularities is why we have human officers. That being said, I always like
appreciate it when people make it easier for me to do my job. Do be warned,
though, that if you do something that really egregiously violates this guide,
I'll probably send an email to remind you, and may threaten Malevolent Paper
Shuffling, the highest penalty awardable by the Office of the Promotor. :)
