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.
• 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 the Medium code block and select the appropriate language to enable syntax highlighting.
• 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.

Plagiarism

Better Programming does not tolerate plagiarism. Copying and pasting someone else’s work and passing it off as your own, without citing them as the source, is theft.

You are more than welcome to quote an organization, the copy from a GitHub repo, the words of someone who inspires you, etc., but you have to let the reader know who said or wrote those words if they are not yours.

Plagiarism is the most common reason that we remove authors from publishing with us.

We’ve written a guide on how to cite your sources if you are unfamiliar on how to do so. Please give it a read:

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 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.
• When referring to database relationships, use Primary/Secondary or Parent/Child terminology.

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 August 17, 2020.