Better Programming Style Guide and Suggestions
How to format your stories like we do
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.)
- “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.
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.
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.
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.
- 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.