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

  • 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

  • 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

  • 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

  • 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

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

  • 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. Our 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

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