Better Programming Style Guide and Suggestions

How to format your stories like we do

Zack Shapiro
Jan 13 · 4 min read
Photo by Braden Collum on Unsplash

At Better Programming, our professional copy editors have a style guide that they make sure every piece meets before we click “publish” so that there is uniformity across topics and authors. It’s part of our commitment to quality, and it’s a filter that we run each piece through.

Here are some tips if you already write for Better Programming, or if you aspire to in the future.


Titles and Subtitles

  • Please make sure your piece has a title and a subtitle.
  • We follow AP style for title capitalization. In title-case, all major words are capitalized, while minor words are lowercase. Title Case Converter is a helpful tool, if you’re not sure.
  • In your subtitle, use sentence-case; this means capitalize it like you would any other sentence (like this one!). Only capitalize the first letter of the first word unless the subsequent word is a proper noun such as a name of a language, person, company, library, etc.)
  • Verbs in titles should be direct (e.g. “Create a JavaScript Library and Publish it to NPM” vs. “Creating a JavaScript Library and Publishing it to NPM”). Leave the “ing” off, please.

How to

  • “How to” should be formatted with a lowercase “t.”
  • If your title includes “How to,” there is no need for a question mark at the end (e.g. “How to Include an External Library in Your React Code?”).

Code Formatting, Gists, and Links

  • Variable names, file paths, URLs, directory names, class names, and values should be code formatted like this. They should not be bolded or italicized unless they are also code formatted and you’re doing it for emphasis. You can code format something by highlighting it and hitting the ` key on your keyboard.
  • If your code is longer than 10 lines, please put it in a GitHub gist with the proper file format. Create a public gist, paste that URL into your Medium piece and hit enter and it should render in your piece. (Note: Medium currently has a bug where it only renders 11 lines of the Gist in Edit mode. The gist will look fine when it’s published.)
  • Please link to languages, frameworks, and libraries if they are not well-known. You don't need to link to Swift, Python, React, Kubernetes, etc., as they are very well-known. You should link to something if it isn’t well-known so the reader can quickly learn more about it.
  • You only need to link that to that resource once. If you reference a React library by name five times in a piece, you only need to link to the first reference.

Header Images

Welcome readers to your piece with a pleasant cover image.

  • Make sure that your piece has a header image with proper credit. Sites like Unsplash are great places to find free-to-use imagery. They make it easy to cite your source, too.
  • Please don’t use offensive or shocking imagery such as people screaming, clowns, or other images that a reasonable person might not want to look at.
  • Try to steer clear of cover images that are too obvious. If your piece is about building a Bitcoin wallet, consider avoiding images of billfold wallets or if your piece is about React Hooks, avoid header images with fishing hooks. Or if your piece is about Docker, try to avoid images of shipping containers.
  • Always cite your images unless the image is so common that it’s basically public domain.

Politics

It’s important to us that Better Programming is a politics-free publication. Readers come here to learn and improve their programming and engineering skills. They can engage in politics and political discussion elsewhere on the internet.

Please steer clear of images, examples, or memes that directly or indirectly reference politics (e.g. direct: images or names of politicians; indirect: making something “great again”). There are plenty of examples that you can use out there. No one ever got mad at a piece with cute dogs or cats in it.


Et Cetera

Other odds and ends that can be useful:

  • Thanking the reader for reading your piece in your conclusion is a nice sign-off, but is obviously not mandatory. They spent part of their day with you and your work, it’s always a nice way to say goodbye.
  • If you have a website, company, newsletter, or another call to action, please include that in your Medium bio, rather than your piece itself. Or copy editors will edit out CTAs that are self-promotional; please don’t include them.
  • If your piece has multiple parts to it, please link to those other parts in each piece so the reader can follow the full series.
  • Consider that the Better Programming audience is professional engineers with prior knowledge and experience. If you feel it makes sense to lay out terms and definitions for the reader, please do so, but try to avoid defining common terms, languages, libraries, and frameworks (e.g. try to avoid “What is JavaScript?” or “What is Machine Learning?”).
  • We use the Oxford comma. Lists should have a comma after their second-to-last item (e.g. Dogs, cats, and birds).
  • Consider including a Resources section at the bottom of your piece with any useful sources you’ve cited in your piece.
  • Please don’t include affiliate links to books, courses, etc. They will be replaced with a non-affiliate link.
  • Please don’t format the starts of paragraph to super-capitalize the first letter.

Thanks for reading. I hope this was helpful. If you have any questions, feel free to leave a response.

This piece was last updated on February 14, 2020.

Better Programming

Advice for programmers.

Zack Shapiro

Written by

Editor of Better Programming (https://medium.com/better-programming). Prev: Director of Engineering at BUMP (YC W18), iOS @ Nano & Splash, early @ Product Hunt.

Better Programming

Advice for programmers.

More From Medium

More from Better Programming

More from Better Programming

More from Better Programming

More from Better Programming

Why Do Incompetent Managers Get Promoted?

1.8K

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade