Writing Guidelines and Tips for Writers

[bph]

From the meeting notes:

From the proposal:

• Follow Make/Core Post & Comment Guidelines for Peer Review and Style and Substance.
• Follow the WordPress Documentation Style Guide

From the discussion, the consensus emerged that this new Developer blog is not just ‘more documentation’. Rather, it’s a place to talk to developers as people, first, and then as members of a community.

To that end, the group agreed that one of the first pages on the blog should be about writing for the blog—both in tone, from the above style guides, and with tips and tricks on how to write, so people will keep reading.

These examples might go on such a page (and drive its tone):

In an open-source environment, there is no imperial we’re making the decisions and doing the things. Specific people, or groups of people, might do things, and the code does things. Spell out who is driving the action.

Use active verbs; the way to get around using we is not to say a thing was done (by magic?), but to say that a person, group, function, or other piece of code does a thing. In a pinch, say a thing happened or got done; at least getting done is a little more active than being done.

Make the reader the star of the show. Walk in their shoes, and lead the way forward, to show what they’ll get from reading the next sentence, and the next, until they see the tangible benefits that come when they do what you recommend.

Look to the Documentation Style Guide for official terminology re: code examples, references to UI elements and technical instructions, so they stay consistent across the teams.

The training and marketing teams have published guidelines that can be screened to ensure consistency across the project.

For using screenshots within a post, this Best Practices for Capturing Screenshots will be a useful guide. Other assets like video, animated GIFs or presentation would need to covered as well.

The blog will also need a set of publishing standards to guide decisions on SEO, excerpt handling, subheaders, featured images, TL;DRs etc.

[bph]

Mary Baum volunteered

[abhansnuk]

@marybaum and @abhansnuk to collaborate on this async and on Thursday September 29, 2022 at 18:00 UTC. Google doc.

Our first step will be to identify sections for the information which will also help async collaboration. We will look for inspiration from other technical writing tips, and by incorporating learning from these, it will also help encourage a wider contribution of submissions.

[abhansnuk]

The following approaches identified by @marybaum and @abhansnuk have been checked as correct for the dev blog with @bph. These will be incorporated into the page content. 1) Audience: Theme and plugin developers, web agencies, individual developers, developers advancing their web knowledge the blog will be a mixture of news, features / tutorials-type [not Learn WP level]. case studies, real world examples that bring more than one features together in a use case or tutorial. This is in line with the discussion on the name of the blog. - CONFIRMED. Action: Further work to confirm tutorials-type for Dev blog versus Learn WP materials, and where there can be overlap/ joint usage to avoid duplication of effort and maximize usage. @abhansnuk to discuss with training

2) Type of content (Incorporating above for ease and to expand as content ideas come in)

• News, longer pieces, case studies, real world examples that bring more than one features together in a use case or tutorial-type pieces (action above on clarity between materials for LearnWordPress.org)
• More posts on this how a dev worked with widgets in and how to accomplish this with blocks. Advantages, disadvantages.

3) Authors' personalities/ opinion

• Authors' personalities should not appear in blog posts. Thus no opinion nor subjective commentary should appear.
• In line with core guidelines for releases, no references to 'we' or 'I'.
• @bph advised: the only exception to the use of 'we' and 'I' references would be specific commissioned pieces of a first person's story.
• Authors/ editors to find works arounds to avoid 'I' and 'we' without falling back to the passive voice.
• CONFIRMED.
• Action: explore a way of visually differentiating the first person's story to be clear to readers. These could also have a different target audience and visually differentiating them, even with a tag, may help reach those audiences.

[bph]

Google Doc where the draft was created

[bph]

Published: Tips and guidelines for writers Huge Thank you to Mary and Abha putting it together.