Wikimedia technical blog editorial guidelines

= Techblog Editorial Guidelines staging =

Overview
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
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 Open Source Software community, and the wider tech industry.

Coverage Technical topics relevant to the Wikimedia technical community, open source, general software development, tooling and technology. The blog will cover specific processes members of the technology and product teams are following/have followed.

The blog will cover topics that intersect with members of the Wikimedia Movement who are interested in the technical aspects of the projects. They may be building tools, creating or following software processes, engaging in project management, interested in specific data points, etc.

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

Audience(s) The target audience of the new tech blog are engineers and other technical folks, other Open Source organizations and communities, and the broader tech industry. The audience for this blog has 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, etc.

Authors

Posts are written by members of the Wikimedia Technical Community. This includes both paid staff and volunteers.

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 Developer Advocacy Team.

Will your idea make a good blog post?
If you have an idea for a blog post and would like help deciding whether it is appropriate for the tech blog, please reach out. The admins can work with you to help shape your idea and get you started with writing.

Prewriting
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

 * Language: (We need to decide on a policy for this as a group)
 * Length: Blog posts should be at least 500 words long.
 * Format: Draft posts in Google Docs, MS Word, LibreOffice, or user page on MediaWiki (We could conceivably use Github for this, too)
 * Style Conventions: Whenever possible, the tech blog adheres to the style conventions laid out in the Wikimedia Manual of Style. 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. Include alt text to describe images for individuals who use screen readers.

Peer review and editing
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.

(This is where we will want to point to the Phabricator process for publication management)

Blog admin review and editing
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
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.

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
You'll receive an email when your post has been published to the Tech blog.

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

You are encourage to share your post widely.

Grand idea product launch

 * 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

 * 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

 * 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

 * 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

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

Technical explanation

 * 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

 * 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

 * 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

 * 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)

 * 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]?

Length
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

 * 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
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
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
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:


 * https://www.languagetool.org/
 * https://editsaurus.tylerwalters.com/
 * https://grammark.org/dist/#/

Publishing on the Techblog

 * Something here about not being able to publish everything

There are a couple of ways to propose and publish on the Wikimedia Techblog

Early stages


 * 1) Share an idea for a blog post
 * 2) Submit a post you have already written

Once you've shared your post with the techblog administrators


 * 1) Editing
 * 2) Scheduling
 * 3) Published

Share an idea for a blog post
It is ideal to start here.

If you have an idea for a post for the Tech blog, please reach out to the administrators before you have written your post. The tech blog administrator can help you shape your idea into a blog post.

Submit a post you have already written
If you have already written a post that you want to publish in the tech blog, check to make sure it fits the editorial guidelines (Link) before contacting the tech blog administrators.

=Sections I'm not sure about yet=

Writing in languages other than English or translation

 * We should have information about writing in multiple languages and translating posts.
 * We should provide tips for writers working in ESL.

Editorial voice
The Wikimedia technical community is composed of many different kinds of people and ideas. While the administrators of the blog aim to maintain a unified style ad format for posts, writers are encouraged to sound like themselves.

Editors will work with writers on finished posts to make sure they are clear, concise, and grammatically correct but will make every attempt to preserve the voice and style of the writer.