Wikimedia technical blog editorial guidelines

From MediaWiki.org
Jump to navigation Jump to search

Overview[edit]

This guide is intended to assist you, a member of the Wikimedia technical community, through the process of authoring a post for the Wikimedia technical blog and working with the blog administrators to review, edit, and publish your post.

About the Tech Blog[edit]

Purpose
The Wikimedia Tech Blog is intended to provide a supportive, well-indexed venue for members of the technical community to share posts focused around more complex technical topics associated with Wikimedia, the Free and Open Source software community, and the wider tech industry.

Areas not covered
Policy or advocacy, Wikipedia and other content based projects (ones w/editor | reader) workflow (other than technical aspects)

Audience(s)
The target audiences for the new tech blog are engineers and other technical folks, other Open Source organizations and communities, and the broader tech industry. The audiences for this blog will have a generally high level of technical proficiency.

Readers are typically members (or potential members) of the Open Source software movement and/or the Wikimedia technical community. Readers have an understanding of computer science, software development, engineering processes, technical concepts, etc.

Authors

Posts are written by members of the Wikimedia technical community. This includes both paid staff and volunteers. Authors on the blog will not receive monetary compensation for their content.

Diverse voices and perspectives are important to the work of the Wikimedia movement. Everyone with an idea is encouraged to propose stories for the Wikimedia technical blog. Topics should cover technical information related to Wikimedia technical projects and Open Source technology.

Administrators

The Wikimedia Tech blog is administered by the Wikimedia Foundation Developer Advocacy Team.

License
Unless otherwise stated, the content will be published under a CC BY-SA 4.0 international license.

Writing your blog post[edit]

Will your idea make a good blog post?[edit]

See Outlines for topics for ideas.

If you have an idea you would like to explore more refer to Publishing in the technical blog.

Prewriting[edit]

Before you write your post, please consider the following:

  • Audience: Keep in mind that the Tech blog is intended for audiences in the Wikimedia technical community, individuals working in Open Source, and the wider technical industry. Material in your post can be technically sophisticated
  • Goals: Your main goal is to convey information that will be interesting and useful for the above audiences. What are your secondary goals?
  • Deadline or intended publication date, if the post needs to go out in a certain timeframe. Please get in touch with us at least two weeks before any deadlines.
  • Approvals: Make sure to check in with other stakeholders and collaborators to ensure the post is appropriate and approved for publication

Writing[edit]

  • Language: To start, blog posts will be in English. As capacity grows, the admins will review processes for accepting posts in multiple languages.
  • Length: Blog posts should be at least 300 words long.
  • Format: Work with the tech blog admin to determine the best format to compose and review your work in. Google Docs, Microsoft Word, and LibreOffice can be useful for drafting. You can also draft on wiki, as long as the information is not sensitive and does not need legal review. Posts drafted in HTML and Markdown are also acceptable.
  • Style Conventions: Whenever possible, the tech blog adheres to the style conventions laid out in the Manual of Style of English Wikipedia. You may also refer to the MediaWiki Technical Style Guide as a supplemental.
  • Titles and section headers: Keep these concise and clear. Use sentence case.
  • Images: Online readers like images. Each post should have at least one. Include freely licensed images only. English Wikipedia's image use policy page can help guide you to choose images that are appropriate for the technical blog. Include alt text to describe images for individuals who use screen readers.

Publishing on the Tech blog[edit]

There are a couple of ways to propose and publish on the Wikimedia Tech blog:

  1. Share an idea for a blog post
  2. Consider a post you have already written

Once you've shared your post with the tech blog administrators:

  1. Reviews and Editing
  2. Scheduling
  3. Publishing

Share an idea for a blog post or consider a post you have already written[edit]

To share ideas for blog posts or to have a blog post you have already written considered for publication, please create and fill out this Phabricator task with all of the questions completed.

You will need to sign up for a Phabricator account in order to do this.

A tech blog admin will contact you about the next steps.

Reviews and Editing[edit]

Peer review and editing[edit]

Writing is a collaborative effort, and we suggest you have your post reviewed by others before submitting it for publication in the tech blog. Peers, teammates and volunteer editors from the technical community can provide early feedback and perspectives that will help improve your post.

Blog admin review and editing[edit]

Once you feel your post is ready for publication, let the blog admin know. They will read your piece, ask some questions and provide some advice and editing.

The admins may ask for additional details like sourcing material, or other material to ensure that the post is factually accurate. They may ask you to make some substantive changes to the post before it is ready to publish. In some cases, they may need to have your post reviewed to ensure it does not violate any legal or privacy policies.

Notes Not all posts will be appropriate for the tech blog, and the admins will have discretion in publication decisions. Whenever possible, they will work with you to resolve any outstanding issues, to make sure the post is readable by the appropriate audience, or direct you to other venues where it may be more appropriate to publish your post.

Scheduling[edit]

When these edits are finalized, we will add a comment to your document, move the document into the approval process, and set a date for it to be scheduled. Very rarely, there could be a situation where we are not able to publish a post after seeing the draft for some reason. If that happens, we’ll try to work with you to fix the problem, but we do reserve the right not to publish something if we don’t think it’s right for the Wikimedia Technical blog.

We maintain a private editorial calendar to schedule upcoming posts. This schedule is subject to frequent changes, based on other content in the pipeline and the approval process. Please let us know if you have any deadlines we should know about. At this step, we also need to finalize images.

Published[edit]

You'll receive an email when your post has been published to the Tech blog.

Sharing your blog post[edit]

Once your post is published on the blog, the administrators will share it on Twitter @mediawiki and @wikimediatech and Facebook.

You are encouraged to share your post widely.

Not all ideas or submitted content will be appropriate for the tech blog[edit]

Please note that not all ideas or submitted content will be appropriate for the tech blog. Please make sure you read the sections about the appropriate types of posts for this venue before you submit.

Outlines for topics[edit]

Grand idea product launch[edit]

  • What was launched
  • The problem we addressed
    • Include brief background information on problem
  • How was the problem solved?
  • One interesting fact about the development process
  • What’s next?
  • Call to action if applicable.

One detail product launch[edit]

  • What was launched
    • an important detail that makes the launch unique
  • Explanation of detail and why it’s interesting
  • Connection to larger goals or objectives
  • Summary of other things people can find in the product
  • Call to action to explore product or otherwise engage

Product update[edit]

  • What’s the new feature
  • Link and summary of previous work
  • Deeper explanation of the feature
  • Explanation of either an interesting technical detail of the feature or an important step in the development of the feature
  • Connect the feature back to goals
  • Next steps

One thing I learned[edit]

  • Brief explanation of your project and your work on that project
  • Introduction of interesting thing(s) you learned
  • Further explanation of what you learned
  • The impact this thing had on your work
  • How this is relevant to other projects/teams
  • Point to documentation or artifact if it exists
  • Question or call to action

Explainer for complicated tech concept or process[edit]

  • Explain a tech concept or process and why its important
  • Connection to larger outcome or goal.
  • Why it’s important
  • Conclusion

Technical explanation[edit]

  • Explanation of the topic or feature this technical explanation applies to
  • Your goal in developing this technical fix
  • What you did
  • Why you did it
  • How this has positively impacted your project
  • Connection to larger outcome or goal
  • How this can be reused outside your project
  • Call to reuse/adapt

Technical how-to[edit]

  • What this guide will teach you
  • Who this guide is useful for
  • Summary of guide content
    • Multiple headings, paragraphs with bolded intros, or a bulleted list are best
    • Concise explanations with code samples if applicable
    • Downloadable artifacts if applicable
  • Why we think this type of information is useful
    • And how it’s improved our projects
  • Call to action and links to additional resources

Announcement of new policy related to technology[edit]

  • Announcement of new change
  • 2 additional important details
  • How this change fits into larger mission or goals
  • Additional small or technical details
  • Thanks, connection back to policy and moving forward

Innovative work in technology[edit]

  • Who, what, when of someone doing something incredibly innovative
  • Why it’s important or noteworthy
  • Additional details
  • How people can learn more

Interview with Technical Community member(s)[edit]

  • How did you come up with that idea?
  • What inspired you to do [X]?
  • What are your next steps?
  • Can you detail how [Wikimedia project] helped you do [X]?

Tips for better blog posts[edit]

Length[edit]

Aim for a minimum of 300 and a maximum of 1,000 words in order to keep the attention of your readers.

For longer form articles, provide a concise summary at the beginning so readers will have a preview of the post's contents.

Accessibility[edit]

  • Charts or graphs: make sure that the colors are accessible.
  • Alt text: Include alternative text describing your images. This is important for individuals using screen readers.

Language[edit]

It's okay to sound like yourself, but be aware of your readers. Try to keep your language concise and clear.

Try to avoid using phrases, metaphors and colloquialisms that might be unfamiliar to a global audience. Avoid Wikimedia "in-jokes" or humor that might not resonate with the audience.

Attribution[edit]

All images used on the Wikimedia Tech Blog must be freely licensed and have proper attribution. For screenshots of Wikipedia articles, this will include attributing the text and license (CC BY-SA 3.0), along with separate attributions for any images included in the screenshot.

If you're also uploading the screenshots to Commons, you should probably tag those images with Template:Wikimedia-screenshot.

Spelling, grammar and writing aids[edit]

Many writers benefit from running spelling and grammar checks on their work. Not only can these check for issues with your document, they can help you become a better writer by identifying your more common errors.

Some Open Source options: