Wikimedia technical blog editorial guidelines
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. Topic areas such as Policies or advocacy, Wikipedia and other content based projects with editor or reader workflows (other than technical aspects) are Out of Scope for the Blog
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.
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 Program Management Team.
License
Unless otherwise stated, the content will be published under a CC BY-SA 4.0 international license.
Writing your blog post
[edit]Before writing
[edit]Prior to crafting your post, kindly take these key points into account:
- Topic: See Outlines for topics for ideas. If you have an idea you would like to explore more refer to Publishing in the technical blog.
- Audience: Keep in mind that the Tech blog is intended for audiences in the Wikimedia technical community, individuals working in Open Source, engineers and other technical folks, other Open Source organizations and communities, the wider technical industry. Material in your post can be technically sophisticated as readers have an understanding of computer science, software development, engineering processes, technical concepts, etc.
- 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 the blog admins 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. For Staff: Talk to your manager about your interest in writing a blog post so they are not surprised when you ask them to approve it once it is written.
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: 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. If necessary, reach out to the tech blog admin to determine the best format to compose and review your work in.
- 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 should have a featured image (the image at the top of the blog). This image should be a high-quality photo, not a graphic or illustration. If you have a photo you would like to use for this, please let the admins know when you propose your post. Otherwise, they can help you choose one. Wikimedia Commons can be a good source of images for your post ( 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. If using images in the post (Photos, graphics, and illustrations are acceptable in the post body), ensure they're high-quality, properly credited, and have a reusable copyright. For self-created images, upload to Commons with a suitable copyright for blog reuse.
Publishing on the Tech blog
[edit]Reviews and Editing
[edit]Peer review and editing
[edit]Writing is a collaborative effort. A good practice would be to have your post reviewed by others before submitting it for publication on the tech blog. Peers, teammates, and volunteer editors from the technical community can provide early feedback and perspectives that will help improve your post. A good practice in writing, as in coding, is to get the text +1ed by someone familiar with the topic and good writing.
Submit your post for review
[edit]All draft posts should be submitted through the Phabricator workboard. Once your draft is finalized and has successfully undergone peer review, kindly proceed to include it within the "Needs Review" column. If your draft is still a work in progress, please ensure its placement within the "Draft in Progress'' column.
Blog admin review and editing
[edit]Once you've shared a draft of your post with the blog admins by adding it to the “Needs Review” column, they will review it for clarity, style, and grammar and will provide feedback and suggestions for edits you can make to further improve your post.
The admins may ask for additional details like source 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 by a third party to ensure it does not violate any legal or privacy policies.
Once the draft is complete, the blog admin will move it over to the blog to prepare it for publication.
Scheduling
[edit]When these edits and the images are finalized, the blog admins will add a comment to your Phabricator task, move the Phabricator task into the approval process, and set a date for the blog post to be scheduled. The blog admins maintain a private editorial calendar to schedule upcoming posts.
A note about deadlines
If you know you have a deadline, please make sure to inform the blog admins ahead of time and to confirm with them that the deadline can be met. Publication timing can depend on the amount of editing required or the number of posts already in the pipeline.
Published
[edit]The blog admins will publish the post and will reach out to you through the Phabricator task and ask you to review it one more time to ensure there are no errors or corrections that need to be made. Once you approve, the blog admins will announce the published post on social media and resolve the task.
Sharing your blog post
[edit]Once your post is published on the blog, the admins will share it on Twitter @mediawiki and @wikimediatech and Facebook.
You are encouraged to share your post widely.
Outlines for topics
[edit]Big picture
[edit]An overview post about a consequential launch, migration, new feature, etc
- What was launched, migrated, updated
- 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.
Examples:
- https://techblog.wikimedia.org/2020/05/18/a-better-toolforge-upgrading-the-kubernetes-cluster/
- https://github.blog/2020-01-22-how-we-built-good-first-issues/
An important detail
[edit]A focused post about that explores one aspect of a launch, migration, new feature, etc
- What was launched, migrated, updated
- 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
Examples:
- ...
A feature update or explainer
[edit]A post that introduces a new feature or explores a useful or overlooked one
- What’s the feature
- Link and summary of previous work (if available)
- 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
Examples:
- https://engineering.fb.com/data-infrastructure/hyperloglog/
- https://github.blog/2019-06-04-direct-instruction-marking-in-ruby-2-6/
Something I learned or Something that worked well
[edit]A post that explores lessons learned from a project or explores something (a tool, process, etc) that worked well
- 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
Examples:
- https://techblog.wikimedia.org/2020/05/04/using-zulip-an-open-source-tool-for-engaging-participants-in-wikimedias-technical-outreach-programs/
- https://github.blog/2020-02-14-automating-mysql-schema-migrations-with-github-actions-and-more/
Explainer for complicated tech concept or process
[edit]A post that introduces and explains a complicated technical concept or process
- Explain a tech concept or process and why it's important
- Connection to larger outcome or goal.
- Why it’s important
- Conclusion
Examples:
- https://techblog.wikimedia.org/2020/03/24/computational-knowledge-wikidata-wikidata-query-service-and-women-who-are-mayors/
- https://youtube-eng.googleblog.com/2018/04/making-high-quality-video-efficient.html
- https://engineering.fb.com/ml-applications/mars/
- https://www.zdnet.com/article/what-is-cloud-computing-everything-you-need-to-know-from-public-and-private-cloud-to-software-as-a/
Technical explanation: problem / solution
[edit]A post that explores a technical problem or issue you encountered and how you fixed it
- 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
Examples:
- https://youtube-eng.googleblog.com/2018/12/add-stereo-music-or-narration-to-vr.html
- https://github.blog/2019-03-05-vulcanizer-a-library-for-operating-elasticsearch/
Technical how-to / tutorial (and why)
[edit]A post about why a technical process is important and how to perform it
- What this post will teach you and why it is important
- Who this post is useful for
- Summary of post 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
Examples:
- https://www.pcworld.com/article/2918397/how-to-get-started-with-linux-a-beginners-guide.html
- https://www.techradar.com/how-to/how-to-copy-a-directory-in-linux
- https://www.freecodecamp.org/news/what-is-git-and-how-to-use-it-c341b049ae61/
- https://plan.io/blog/technical-documentation/
Tech community events and outreach programs
[edit]A post that explores community events and outreach programs
- What is the event or program and why is it important
- Share the details of the event or program
- Highlight a few of the outcomes
- Lessons learned
- Call to action
Examples:
- https://techblog.wikimedia.org/2020/04/30/google-code-in-2019-the-next-generation-of-technologists-contribute-to-wikimedias-code/
- https://techblog.wikimedia.org/2020/04/27/organizing-and-running-a-developer-room-at-fosdem/
Interview with Technical Community member(s)
[edit]An interview with someoone in the technical community
- 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]?
Examples:
- ...
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
Examples:
- ...
Announcement of a change 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
Examples:
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: