Skip to content

Latest commit

 

History

History
116 lines (86 loc) · 4.56 KB

EDITING.md

File metadata and controls

116 lines (86 loc) · 4.56 KB

Perl Advent Calendar Editor Style Guide

This style guide is not meant to be a set of rules, but a resource for editors to refer to when in doubt and hopefully a source of inspiration for them on their AAdvent Calendar editing journey.

Purpose

The goal of this style guide is to assist editors of the Perl Advent Calendar in maintaining a consistent yet diverse and welcoming tone across all articles. Editors can help to ensure clarity, correct grammar, and spelling, while preserving the unique voice of each author.

Editorial Philosophy

  • Light Touch: Applying minimal editing can help to maintain the individuality of each article and avoid making articles sound uniform or overly polished.
  • Respect for Non-Native English Speakers: We welcome contributions from authors whose first language is not English. We can work to preserve their voice as long as the intent is clear and the grammar and spelling are correct.
  • Encourage Creativity: Articles often incorporate Christmas themes and whimsical elements. We can encourage authors to use festive variable names and storytelling to engage readers.

General Guidelines

1. Article Structure

  • Introduction: The opening should clearly introduce the module being discussed and its significance.
  • Body: Integrate code examples with descriptive text. Keep a balance between technical detail and engaging narrative.
  • Conclusion: Summarize the key points or include a final, complete script with comments if applicable.

2. Tone and Voice

  • Consistent but Flexible: Ensure spelling and grammar are correct but preserve the author’s original tone and style.
  • Engaging and Entertaining: Traditionally articles are light and in the spirit of the holiday season. Examples and stories involving fictional Christmas characters are encouraged but never mandatory. An article lacking in any kind of holiday subject matter is just as welcome as a story about Santa, elves, reindeer, etc.

3. Technical Accuracy

  • Verify that code snippets are correct and functional.
  • Ensure the article’s technical explanations are accurate and clear.

Formatting Guidelines

  • Use of POD: Articles should be formatted using POD (Plain Old Documentation). Refer to past articles for formatting examples.
  • HTML: Use =for html or =for web_only and =for rss_only for adding custom HTML if necessary.
  • Code Blocks: Include code interspersed with explanatory text. Final scripts at the end should be well-commented.
  • Graphics and Media: Encourage authors to use relevant images, graphs, and even animated media. Examples include:
    • Animated GIFs of terminal output
    • SVG Christmas-themed graphics
    • Interactive JavaScript elements
    • Holiday-themed images from public sources

GitHub Etiquette

  • Using GitHub pull request suggestions is a good way to suggest typo fixes and other changes which would otherwise be difficult to explain

Editorial Process

1. Initial Review

  • Check for technical accuracy and completeness.
  • Provide feedback for areas requiring clarification or expansion.

2. Edits and Suggestions

  • Correct typos and minor grammatical issues.
  • Suggest improvements that enhance readability or engagement, but do not impose major rewrites.

3. Final Review

  • Ensure all edits have been incorporated and the article renders correctly.
  • Confirm that all code has been tested and works as intended.
  • Make sure the article fits within the Christmas theme and follows the general tone of the Perl Advent Calendar.

4. Post Merge

We may still make minor edits (spelling, grammar, broken links, etc) to articles after merge. If an article would require dozens of comments to fix typos etc, it may be easier simply to merge it and then fix typos before publication. This process should be fun, so we don't want to make it too onerous for authors and editors alike.

Key Dates

  • September 30th, 11:59 PM EDT: Deadline for article proposal submission.
  • October 1st, 11:59 PM EDT: Notification of article acceptance.
  • November 1st, 11:59 PM EDT: First draft submission.
  • November 15th, 11:59 PM EST: Final article edits due.
  • December 1st, 12:00 AM EST: Articles go live as Advent begins.

Final Notes

We aim to foster an inclusive and collaborative environment. Editors should maintain open and positive communication with authors, encouraging creativity and diversity while upholding quality and clarity.

Thank you for being part of the Perl Advent Calendar editorial team. Your work helps make this beloved tradition possible!