Editorial Guidelines for Developers and Data Scientists

Some simple does and don’ts for writing a compelling technical blog post.

These editorial guidelines have been modified and updated from the ones written originally by my brilliant former coworker, Mike Broberg. These are the guidelines we still use at The CODAIT Data Lab. These tips should get you up and running, and meeting your blogging goals for 2020 in no time.

My first bit of advice before you sit down to write is to make an outline for your post and then talk to someone about your ideas. If you are targeting a specific publication for your content, then reach out to them and ask if they have a particular content strategy in place. A “content strategy” basically boils down who the audience is for a particular publication and what they expect from the content that is delivered there. Think about whether the post you are writing will appeal to this audience and why.

Woman behind a laptop with GitHub Octocat stickers on it with her glasses in the foreground. Image courtesy: #WOCinTechChat from Flickr.

What to Do

• Images: It helps to have at least one image, even if it’s only a project logo or meme. If you can’t find what you’re looking for, ask a friend for help. Videos are also great. So are gifs! Attribute all imagery whenever possible. Some great resources for stock photos can be found at Unsplash and #WOCinTechChat.
• Article titles: Give your article a rather short handle. It’s OK if it’s a little irreverent, since the subtitle can provide more context. Alternatively, you can say what your code is doing. From there, the subtitle can simply say how you’re doing it, or what interesting tech you’re using to do it.
• Title formatting: All articles need a title and a subtitle. Try to keep article titles under 12 words and capitalize all words that are four letters or more. Article subtitles can be longer than 10 words and take sentence case. Here are some handy title formatting rules.
• Subheadings: Take a cut at article subheadings. Even if you think yours are bad, they at least give us an idea as to how you want to structure your article.
• Code snippets: Use GitHub gists for any simple code snippets over three lines. (Think command line tasks or import statements.) If your lines are particularly long or dense and less then three lines, it’s still OK to use gists if you feel it would benefit from syntax highlighting or horizontal scrolling NOTE: It’s good to build your gists with your own GitHub profile so you get the credit rather than reposting someone else’s gist.
• If you have a simple JSON doc, a Medium-style code block is OK.
  — Medium specific tip: If you’re editing in Medium, to format inline code, highlight the text and hit the backtick key. For pre-formatted code blocks, highlight and hit `command + option + 6` (`Ctrl` instead of `command` on Windows).
• Architecture diagrams: Review the high-level architecture of your app, if applicable. draw.io is a good free web app for creating architecture graphics.
• Topic sentences: “Topic Sentences” are basically sub-headers within your article that break it up into sections by topic, or step in the process. Try to keep topic sentences short and to the point. If you build an outline, it will usually form the basis of your topic sentences.
• Lists: Lists are often a nice way to lend visual contrast to an article. If you find yourself doing a lot of listing within your paragraphs, consider ditching the commas and breaking out the bullets instead.
• Speaking of bulleted/numbered lists, if you don’t know how to introduce one, start it by using the “Here is” structure. Eg: Here’s an example: …

What to Avoid

This list collects style issues I most frequently see while editing. Take these suggestions with a grain of salt. There’s usually a good reason to break them.

• Don’t write a procedural list of steps to deploy/configure/run a sample app. The exception to this rule is a contributed article to a different Medium publication. If they have separate style guidelines or expect in-depth steps for their readers, then follow that format.
• Never use images to insert code snippets. It’s problematic for folks using screen readers and aside from that you have no control over how it renders in the browser. You want all your readers to be able to see your code no matter what.
• Don’t worry about starting a sentence with a conjunction. It’s fine.
• Don’t embed links on “here.” For example: “You can find out more info about AI Fairness 360 here." Much better: “The Ai Fairness 360 website has more info.”
• Avoid most semicolons. In general, prefer shorter sentences.
• Don’t worry about Medium’s estimated reading time. Articles with lots of code samples will appear faster to read than they really are. The optimal reading time for a text-heavy article, according to Medium, is 7 minutes.
• Don’t worry about small differences between U.K. and U.S. written English. (For example, spelling or positioning of punctuation within or outside of quotation marks.) Just make sure you subscribe to one or the other, depending on your audience.
• Try not to use “we” to address the reader. The writer will not be coding alongside the reader, so try to use “you” to address readers. If you find yourself issuing a series of instructions, it’s fine to then use the imperative form and simply drop “you” as the subject of the sentence. Conversely, the author of the article can refer to themselves as “I” or to “the code” as the subject of the sentence.
• Speaking of sentence subjects, avoid passive voice. Sometimes it’s unavoidable, especially in documentation scenarios, but avoiding it typically results in stronger, more active sentences. For example, it’s the difference between The data is parsed by the display function and automatically produces a vizualization (passive voice) and The display function parses the data and automatically produces a vizualization (active).
• I don’t know if this still needs to be stated in 2020, but avoid iframes at all costs.

Types of articles

• Project write-ups: Write about what your app does and its high-level design. Try to include an architecture diagram. No need to explain every relevant function or deployment step. Handle those in the documentation or project README.
• We prefer write-ups for a blog format over full-scale tutorials. Shorter articles are generally less stressful to write, quicker to publish, and easier for your audience to consume. Three flavors of write-up:

1. Web app: For example, an app using TensorFlow.js, PoseNet, and the Web MIDI & Web Audio APIs by va barbosa.
2. Notebook: Ideally featuring visualizations or shaping of large data sets.
3. Productivity tool: For example a command-line utility written to make your life (and others!) easier or more fun.

• Best practices: Usually for how to best use a particular tool or data set, or for explaining your options with particular libraries.
• Hot new trends in tech.
• Community & event recaps: Articles about engaging with development communities can be fun! Wrap-ups of interesting events are also useful, as some attendees will engage with the article because they wished they could have attended. Recaps and takeaways from a particularly interesting talk are good too.
• My advice is to avoid posts that promote upcoming webinars and speaking engagements because this content has a short shelf life, once the event happens the article loses a lot of relevance. Instead, you could write a technical article relevant to the subject matter of your workshop or talk and then promote upcoming talks, webinars, events, etc. within it.

Go Forth and Write!

Those are the tips are I share with the folks on my developer advocacy team about what to consider when writing their blogs. If you want to start writing more about your technical projects the best advice I can give is to just schedule some time to sit down and start. The second best advice I can give is go read Stephanie Morillo’s new book, “The Developer’s Guide to Content Creation” because I just got my copy and I can’t wait to read it!!!!