At ScaleMath, one of our specializations is producing technical content for companies that want to reach a developer demographic. Please refer to and follow our style guide (which is broken up into four sections below) – and do not hesitate to reach out to ask questions if you have any:
1 – Voice
Write in Second Person
Readers want to feel as if they’re being directly addressed and spoken to. So, speak to your readers directly using “you” and “your.” Avoid “we” and “our.”
Good:
You can use a web browser (like Chrome, Safari, or Edge) to access websites on the internet.
Bad:
We can use our web browsers (like Chrome, Safari, or Edge) to access web sites on the internet.
Communicate To The Reader In Their Language
Use Conversational, Appropriate Language
Whenever producing content, you shouldn’t even start writing if you don’t know exactly the type of person you’re writing the piece of content for. Even as you start writing, continuously read your article out loud and ask yourself, “Would I speak like this about this topic to the people I’m writing this for?”. Use real-world experience and avoid jargon when possible.
Good:
Experts agree that the internet was not the product of any individual mind, but a series of advances in networking and computer science.
Bad:
Many scholars would agree that, had it not been for active networks, the simulation of Lamport clocks might never have occurred. The notion that end-users synchronize with the investigation of Markov models is rarely outdated. A theoretical grand challenge in theory is the important unification of virtual machines and real-time theory. To what extent can web browsers be constructed to achieve this purpose?
Nobody Likes Wordy Content – Do Not Repeat Yourself
Nobody likes wordy content, but trust us when we say developers really can’t stand reading redundant statements. Eliminate wordiness, you wouldn’t repeat yourself when programming and shouldn’t do so when writing either.
Good:
A lively debate rages among software developers. The contentious issue is: tabs or spaces?
Bad:
There is currently a lively, ongoing controversy among many computer scientists and other professional in the field of software development: theories are being spun and arguments are being conducted among them about whether the use of tabs to designate indentation in a document is superior to the use of spaces for the same purpose.
2 – Content
2.1 – The Introduction
Every article should have an introduction that typically spans 1-3 paragraphs. A good intro needs to answer three things right away:
- What is the pain point I’m addressing here? How do I hook my readers?
- What’s the solution to their problem?
- What am I going to do in this article? (i.e. what will I be walking them through to demonstrate how to solve their problem?)
Sign off your introduction by letting the reader know that you’re going to teach them how to solve this pain point.
2.2 – Support Every Claim With Evidence
Whenever making a claim, you must ask, “How can I prove this so that it actually means something to the reader?”
Some examples of ways to do so include:
- Including a link to a reputable article
- Including a quote from another source
- Citing an academic study
- Linking to the official documentation
- Interviewing knowledgeable professionals
Good:
While Postgres can handle hundreds of columns, it might not be a good idea to take advantage of this feature.
Bad:
While I’m guessing Postgres can handle a lot of columns, it might not be a good idea to use more than a hundred if you can help it.
2.3 – Plagiarism and Copyright Infringement
Written content that is copied directly from another source must be quoted and cited appropriately. Switching out a few words in a sentence is not enough to make the content original, so be sure to put everything in your own words.
The bar for using images is even higher. You may not use images from another website unless they expressly allow it. If you need stock images, use a site like Unsplash or leave detailed notes about images you would want designed in your G Doc so the editor can help with this step/loop in a designer to get infographics, etc.
2.4 – The Conclusion
Every article should include a conclusion that spans 1-2 paragraphs. The goal is not to restate in as few words how to solve the problem again as this would be repeated from the body of the article. Instead, it should restate the thesis of the article, reminding readers what they learned as well as referring them to other resources readers may be interested in at this stage.
(and for many of our clients also inviting them to drop a comment if they want to join the conversation / have any questions)
Good:
While JSON data types come with some drawbacks, they are useful when you need more flexibility in your data structure. Thanks to Django’s native support for `jsonb`, you can get started using JSON data in your web applications without learning all the native Postgres query operators.
Next time you need more flexibility in your data model and want to benefit from the strengths of Postgres give `jsonb` fields a try.
3 – Conventions
All articles should be written in the Google Doc included in the Asana task.
Use Headings to Break Up Sections & Create Content Structure
Content that has actual structure is much more enjoyable to read.
Use H2s, H3s, and H4s to break up your content into sections.
All headings should be written in title case.
Good:
How to Use JSON Fields in Your Python Application
…
The Two JSON Formats Supported by Postgres
…
Bad (not title case):
How to use JSON fields in your Python application
…
The two JSON formats supported by Postgres
…
Denote Code with The Code Blocks G Doc Extension
Denote a code block using this Google Doc extension so that the editor that will be responsible for uploading this piece to the client’s CMS will know what this section should appear like.
Use inline code when referring to a variable name or short command in context.
Good inline code example:
Call the `snafu()` method to exit and return to your command line.
Bad inline code example:
Call the “snafu()” method to exit and return to your command line.
Use Double Quotes for Quotations
And use blockquotes when the quote is two or more lines long.
Good:
Some text leading up to the quote.
> “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.”
Some text after the quote.
Bad:
Some text leading up to the quote. “The field/element/path extraction operators return NULL, rather than failing, if the JSON input does not have the right structure to match the request; for example if no such key or array element exists.” Some text after the quote.
Use inline quotes when the quote is relatively short or when you’re referencing a single word or phrase.
Good:
“There’s nothing to see here,” according to John.
Bad:
> “There’s nothing to see here.” – Davies
Use Emphasis Effectively
Use italics to emphasize text or use bold to suggest strong emphasis.
Good:
There is nothing as important as using spaces to indent your code.
4 – Communication
Communicate Delays and Roadblocks Proactively
You will not be penalized or criticized for late work if you maintain active communication with us about the assignment. And we are able to offer technical help and extensions but you have to provide us with reasonable notice before the due date for steps to be taken.
Good:
Hey – I know the Postgres article is due next week, but I’m running into trouble. Would you be willing to hop on a quick call and explain the JSON fields in Postgres? Or do you have any resources that might help me out?
Bad:
Hey – I know my Postgres article was due today, but I’m not able to figure out the JSON fields in Postgres. Could I have an extension until next week to struggle with it more?
Team members who miss deadlines without communicating continuously may (if full-time) be subject to disciplinary action or (if part-time) no longer be eligible for future assignments.
Remain Responsive & Available in Asana & Slack – We’re A Team After All
We’re big believers in asynchronous communication but async communication doesn’t mean bad communication. We always want our entire team to feel comfortable and openly communicate with us where they are at with content. If you get a message, be honest and set a clear expectation – don’t hide until something is complete and then message saying it is delivered.
This is unhelpful to both of us because all it means is we have to keep sending unexpected messages out of the blue.
Good:
Hey – thanks for the update on this article. I’ll keep that in mind while I’m working on the piece.
Bad:
Hey – sorry, but I didn’t see your email until today, and I know the article is due now. I’ll try to incorporate your feedback before midnight if I can.
Team members who continuously fail to respond to messages or openly communicate with the team will not be eligible for future assignments.
Further reading: Google’s developer documentation style guide, DigitalOcean’s technical writing guidelines.