Made in Chicago Company Directory

Want to write for the blog? Terrific! Here are some helpful hints to help you get started, get published, and—most important—get noticed!

The dev blog is for original material

Your post can be about a variety of topics of interest to developers — a news item, a technique you’ve tried with WordPress, a roundup of several approaches to a problem. Or anything else you think a modern WordPress developer of plugins, themes, or sites would find useful and interesting.

You’re the author. Your organization is not.

Your piece should be yours. It should represent you, not your organization. So in the Author field (in the image, its label is circled in red) please use your personal wordpress.org username, which in turn will link back to your profile.

Credit your collaborators

You can have co-authors, and you may want to add other voices to your own. You may have sources for your news.

You will also have reviewers and editors.

Please credit them all, using their wordpress.org usernames, and if possible, please leave out personal details like their gender or their age.

Who are you writing for?

This new resource is for developers across the WordPress community. It’s a place where developers from every part of the ecosystem can come together and talk as people, first, and then as part of the community.

Your reader might be a theme and plugin developer (sometimes called an extender) or someone doing client work in a web agency. They might also be a freelancer, or someone who is learning to code.

On the other hand, have you ever met a developer who was not always learning something new? Because if there’s one constant here on the web, it is that everything changes.

Follow the guidelines

You will often hear that the most compelling feature of WordPress the software is the WordPress community. And part of what binds the community together is a set of standards that govern the way contributors communicate about the project.

Those guidelines live in these places:

The WordPress Brand Writing Style Guide, newly updated for 2022 and beyond
Make/Core Post & Comment Guidelines for Peer Review and Style and Substance
WordPress Documentation Style Guide for official terminology re: code examples, references to UI elements and technical instructions
The training and marketing team guidelines

Some highlights, for quick reference

There is no WE.

You might have heard this old line, that in open-source software, the decisions get made by the people who show up. And, therefore, not by people who have any special skills, expertise, rights of ownership, or any other badges of status.

WE do not do anything; specific people do specific things. So please make that clear, and leave we and us out of it entirely.

NO: ~~“In the meeting, we decided to postpone the event until after the holiday.”~~

YES: “The group at the meeting agreed the event would work better after the holiday.”

For all the same reasons, don’t use I, either, or add your opinion, unless your piece is explicitly about your personal experience. If you want to add your perspective to another kind of article, add it as a comment after you publish.

Capitalization and punctuation

In headlines and subheads, use the sentence case. Only punctuate the end of a headline if it is a question, or a complete sentence whose tone will shade the meaning.

Use the h1 – h6 tags semantically.

In body copy or other text, use one space after a period.

Use the Oxford comma in series. ‘The signs were blue, black, and pink.’

Spelling and counting

Use American spelling and date formats: ‘color’ and November 17, 2022.

Spell out the numbers one through nine. Use numerals for 10 and above. ‘Six people arrived, but they were 15 minutes late.’

And while you can use more to compare things you can count and things that accumulate, you may only use less for things that accumulate. If you can count them, and some are missing, there are now fewer than before. ‘Fewer cows will give less milk.’

If you are discussing in-person events like WordCamps, use local times in schedules. For online events and regular meetings, use UTC.

Be a person, talking to a person

People usually read by themselves. They process your content internally. So you are talking to one person at a time, pretty much always. It only makes sense, then, to make your story about your reader.

(Especially since the WordPress Foundation guidelines forbid the use of I and We, as in ‘We recommend.’)

Talk directly to your reader. Use You and Your a lot.

Make them 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.

As the old poem goes:

“Less, how the [answer] came to be,
And more, what it will do for me!”

– Victor French

But first, be clear

The WordPress community is huge! Your reader probably speaks and reads English. But they are not necessarily from your part of the world, and English is probably not their first language. They are not necessarily your age, and they may know nothing about the culture you live in.

So while it is great to show some personality in your writing, it is more important to be clear.

Keep your prose alive

Before you can solve your reader’s problem, you need to keep them moving through the article.

Three things make that a lot easier: Short words, short sentences, and active verbs. George Orwell, a 20th-century novelist taught in schools across the English-speaking world, put it this way:

Never use a long word where a short one will do.
If it is possible to cut a word out, always cut it out.
Never use the passive where you can use the active.

Those are the middle three of his famous Six Rules on Writing, taken here from a graduate resource on scientific writing at Duke University.

Of these three, by far the most important is the third: there is no energy in a passive verb. Don’t get around the rule about using we by saying a thing was done, or is recommended. Say who did it, or, in a pinch, that the thing got done.

Structuring your article

Your first paragraph

You probably learned in school that you should summarize your article in the first paragraph, so your reader knows what’s coming.

But there are many ways to start an article. One particularly compelling approach is to summarize the problem.

And if you can, do it by telling a story.

Which would you rather read?

WordPress 6.1 consolidates global CSS styles in one place [link] so you can set values for margins, padding, borders, and colors in theme.json and then expose the parameters in the styles editor as you see fit. At the same time, new block-locking controls let writers add content without taking layouts off-brand.

It happens all too often: you spend hours tweaking styles across templates and template parts — margins, padding, container sizes, borders, colors, and more — until your CSS matches your brand almost perfectly. And then a well-meaning author comes along and changes the settings in five blocks.

WordPress 6.1 ends that frustration.

More to the point, which opening paragraph paints a picture of something you might well have experienced, and perhaps more than once?

Granted, storytelling will not always lend itself to your subject. But if you want to get your reader involved from the first line, it is worth considering.

Headlines and subheads

People tend to skim articles before they read them, so it’s a good idea to do two things:

Break up your text with many subheads
Use those subheads as a parallel path through the article

The phrase TL;DR tells the story of a reader presented with a solid gray wall of text. Very few people have the patience to start scaling that wall; it’s so much easier to click away.

So break up your paragraphs. They do not have to be five sentences long! And use subheads every few paragraphs to call out your main points.

Then go a step further, and connect your subheads to each other logically so that a reader can just about skip the text and still get a feel for what’s happening in your piece.

And, again because this is the web, your reader is likely here to solve a problem. Their time is probably limited, and their attention definitely is.

Linking to external sources

There’s a good chance that you’re going to want to build your story with links from recognized authorities. When you write for any part of the WordPress project, you do need to be careful about what organizations you link to. For the most part, you should prefer WordPress-affiliated or open-source sites over third-party commercial sites.

You’ll find some helpful advice in this post from the WordPress Documentation team. In it, @milana_cap gives one list of links that are always good to use and another list that are good to use as long as you verify the accuracy and timeliness of the information people will find on the other end. Any links to official sites of tools and libraries used in WordPress would be in line with this external link policy.

Here are a few more good sources you can pretty much always link to:

The React site
The Mozilla Developer Network (often called the MDN for short) Web Docs in general, and
the MDN JavaScript language overview, in particular

When you’re interviewing a person or consulting a source, you will want to link to them, too. With rare exceptions, identify them as a person (not an organization) and link to their personal wordpress.org profile.

Show as much as you tell.

The web is in large part a visual medium. So, it’s important to show your reader what to do and where they can find the resources they need to do it.

Images and other visuals also help break up that aforementioned gray wall of type.

Below are some thoughts on producing visuals your readers can see well (and how to make them useful to people who can’t see them at all).

Images

Technically speaking, what counts as an image? Any still picture, whether it’s a photograph, an illustration, or a diagram—even a chart—qualifies as an image. So does a screenshot.

The best images focus on exactly what you’re talking about. They’re big enough to show your example clearly. And the resolution is just high enough that it stays clear at most common screen sizes.

For specifics on screenshots, check out this video: Best Practices for Capturing Screenshots from the Learn.WordPress team.

Video

Want to show interactions as they happen? Video is great for that! And on this blog, video files work better than animated GIFs.

When you submit your post, please also send the video as a separate file. The editorial team will upload video to the WordPress CDN.

Focus in tightly on the interaction you’re showing. Record in the highest resolution you can, but preferably at least 1920 x 1080.

Most phones on the market today show at least that many pixels. And many readers are probably using their phone to read your article.

Code snippets

You can write code directly into a block and tweak the look of it in the settings. Show the shortest snippet you can, using the biggest type size you can. Because, again, your reader will very likely be on their phone when they see your piece for the first time.

Accessibility: visuals for readers who don’t see

If you’re a developer, you probably know the basics of accessible images. Use Alt tags and captions to describe your visuals for people who use screen readers, unless an image is strictly for decoration. In that case, leave out the Alt tag.

Give every image a title that means something. Sighted or not, your reader won’t learn much from a screenshot called IMG_5601.jpg, no matter how elegant the code in the picture!

Directory

Tips and guidelines for writers