Editorial Guidelines

Topics

The Perl Advent Calendar articles are articles that are of interest to Perl programmers: They should be seen as a gift that is delivered to a Perl Programmer as they open the doors of the advent calendar each day. This means that they're normally about modules that Perl Programmers can use in their code, though occasionally they're about modules that Perl Programmers can use while developing or debugging their code.

The Perl Advent Calendar should be centered around one core module, though we allow a lot of latitude once that module has been introduced (a good example of this is the Acme::MetaSyntactic article Mark wrote in 2015 which obstinately was about Acme::MetaSyntactic but also was an article on Perl automation on a Mac.) The question we like to ask is "what module name am I going to put in the Topic section at the top right of the page?" You should be able to answer this question.

You should probably check the archives to see if the module you're writing about has been covered before (you can still write about it, but we should discuss it first.) There's two ways to do this: Either look at the index of all modules or check out the repository and run ack over it.

Writing Style

The Perl Advent Calendar is a Christmas advent calendar. This means that if possible your article should have a Christmas theme. This typically happens in three ways:

1. The module itself is used to do something Christmassy. For example the FFI::Platypus article used FFI::Platypus to wrap GL which was used to make pretty snowflakes.
2. Simple theming of variables and example input and output. For example the Redis entry uses Christmas like test data in Redis.
3. Telling a Christmas Story. We imagine the module being used to do something related to Christmas, like Santa testing his sleigh or Trying to automate support so we can get to the Christmas Party

Code, Images, and Tables.

We want to avoid the "wall of text" syndrome in our articles. There's two basic techniques we use for this:

1. We like lots of code blocks interspersed in your article (like traditional pod). We want to avoid having too much prose without any code, or too much code in one go. We really want to avoid the whole story at the start of the article followed by one long script at the end. Break it up, explain as you go! You should also read the guidelines on how to turn on syntax highlighting
2. Images are good. Graphs for figures are handy. Pictures of your editor or web browser. Even the odd occasional purely figurative diagram.
3. We like tabular data where it makes sense, for example the plugins for Reply. The markup for this table is augmented HTML - see the source of that page for an example.