http://www.perlmonks.org?node_id=324056

Janitors' Guidelines

What is janitoring (editing)? Why are we here?

The unfortunate fact is that many posts are made improperly, by people who either don't (yet) understand the spirit or machinery of the site, or are deliberately trying to subvert it. The janitors' mission is to hold the line against utter chaos, to keep PerlMonks tidy and usable. "Tidy" means nodes are in their proper sections. (For junk (troll) posts, this means "the bit bucket".) "Usable" means nodes have meaningful, searchable names, and render readably in the most common browsers.

Note that PerlMonks' janitorial philosophy, while generally conservative, has evolved somewhat over time. To fully appreciate the nuances of current janitorial thinking, janitors should read the editors wiki, preferably in chronological order, understanding that what comes later takes precendence of what went before. Furthermore, understand that janitors serve at the pleasure of the gods, who ultimately determine site policy. All janitors should think first, ask and discuss second, and act third. And remember that janitors never have a "mandate" from the Monks at large.

How do we fulfill that mission?

Mostly, it's about using your judgement; for example, much advice for janitors talks about "reasonable", "significant number", and so on. Even though these guidelines attempt to outline the janitorial site policies that have evolved, ultimately it is up to the current cadre of active janitors to act as they see fit, with PerlMonks' best interests at heart. To be successful in this, janitors must be users with a deep and broad understanding of the history and workings of PerlMonks, and must have an unimpeachable respect both for the author of each individual node, and for the PerlMonks user populace as a whole (including Anonymous Monks).

In most cases, haste is not a virtue. (See below for exceptions.) If you feel uncomfortable about changing a node according to a consideration, then just leave it for someone else to judge. Considerations don't expire. Leaving something alone is always one of the choices! You can also raise the issue in the chatterbox or the editors wiki, and solicit the advice of others.

What do we do?

The watchword is: keep your impact low. If a node needs corrective action on its formatting (i.e. HTML tags), do just enough to make the node render readably, in accordance with the original poster's probable intention. This means, mostly, just adding <p> and/or <br/> tags in cases where the poster didn't realize that the content would be interpreted as HTML rather than plain text. (You can go into the 'edit' view of the node to look at its raw content, and that should give you a good idea of what the original poster was aiming for.) Other types of edits that are occasionally required include adding, moving, or removing <code> tags or <readmore> tags.

Unlike node content, node titles are "property" of both the node author and the site itself, in the sense that title quality has a substantial impact on the usability of the site. Therefore, janitors have considerably more license with titles than with content. Note that when retitling a node, you should retitle all of its children having the same title (modulo any "Re:" part); whereas in cases where the author of a reply has explicitly changed its title to something else, that should not be affected by the retitling action.

Then janitor's job sometimes also involves moving nodes between sections, when they clearly do not belong in the section they were originally posted in. What is consideration? lists which sections a node can be moved between (by janitors). The list of sections and their purposes should already be known by all, but as a refresher, here are the "big three":

Meditations serves an important role as a place for authors to post RFCs and similar draft documents which may ultimately be destined for other sections, most notably the Tutorials section. If someone has posted a tutorial which is clearly not "ready for prime time", janitors should consider moving it into Meditations.

Janitors may also unconsider nodes. If a node has been considered, for whatever reason, and there is a significant number of 'keep' votes (meaning "keep the node as it is"), then there is nothing the janitor needs to do, except to remove the consideration. This also applies to other situations in which there appears to be no useful consensus. One situation in which unconsideration action is mandatory is when a node has been considered for reapage, but it has a reputation high enough to prevent automatic reaping. There are also times when the consensus of the Janitors is to leave a node unchanged despite an affirmitive vote. It's generally advisable to discuss such nodes in the editors wiki.

How do we do it?

We keep an eye on Nodes To Consider and Nodes Requiring Editing (linked as ntc and nre, respectively, in the Editors Nodelet). Any nodes which are considered for editing and have a significant amount of edit votes (and no or few 'keep' votes), we change as appropriate. Judgement is required here, whether a thing should be changed immediately, or whether one should wait for a general consensus to form.

Exceptions to the "easy does it" rule:

  1. Posts which have no formatting whatsoever (and appear to need it). If the output looks just like a block of text, with intermixed code, and data examples. Clicking 'edit' will probably show that the author used newlines and indents, but failed to check the preview. Here it is best to replace consecutive newlines with p-tags, and surround code/data with code-tags. Make sure to /msg the author (using the msg box provided upon updating the node), and point them to Writeup Formatting Tips.
  2. Posts which are clearly offensive and not in the slightest Perl or PerlMonks related.

When changing a post, it is considered a good idea to add a note to the end of it, noting who did the edit, when, and what/why. This usually goes something along the following lines (this is just an example):

<p><small><i>2013-12-11 [vroom] Added code tags</i></small></p>

Just a brief description will do. When retitling a post, it's nice to put the previous title here, so people/the author figures out whats happened. If an entire thread is retitled, we only place a janitorial attribution in the base node being retitled. See Janitor Signatures for some sample janitorial attributions.

Please keep these janitorial attributions neutral in connotation. We shouldn't be using our powers to attach commentary to a post which might influence how others feel about the post. We simply do our job, mark that we've been there, and quietly leave. It is also customary, when unconsidering a node that required no action, to attribute who considered it, why, and what the final vote was, along with who unconsidered it, and why. This is done not to deface a node, but to keep a record of what's been done (or not done). As much as possible, keep it concise.

When we edit a node we should also /msg the author to explain briefly what we did and why. For example: /msg davido "Help Please!" has been retitled to "How do I execute a Perl script?" to promote searchability. Please see How do I compose an effective node title? for more info. Doing so will educate the author so that hopefully the same mistake isn't repeated.

When do we do it?

When we're dead sure that something needs to be changed for its own good (i.e. so that people can actually read it, or find it later).

This bears repeating: There is also the possibility to not do something! If you're unsure about a proper action, leave it for someone else.

What don't we do?

Don't change actual post content!

It's considered very poor taste to change the actual text of a post, even if the bad spelling/grammar is niggling at you. Our aim is to try and present the post as the author originally meant/wrote it. So please don't: correct spelling, grammar, move things around, delete pieces etc.

Exception: Occasionally, a node will be considered to be edited to "remove what seem to be actual persons names/addresses/email addresses, passwords" etc. The author of this faqlet is in two minds as to whether this should be done. Replacing these in code snippets where the author has apparently just imported a local copy of their code, without checking first, would seem to be the only place this should be done.

Don't act hastily!

This means, specifically, don't edit a node just because someone considered it. Never edit a node without reading it and its replies, and taking into account any votes already cast.

Moving posts

If a node has been approved into a section, you should unapprove it before moving it. "Unapprove" appears as a link in the Editors Nodelet.

Note that you must never attempt to move and approve a node in the same step! Or even two steps! You must follow this sequence very carefully:

  1. Move the node (change its assigned section, and submit).
  2. Reload the page.
  3. Approve the node.

Further reading:

See also: Janitor Powers.