This is a step-by-step guide to writing and editing articles for Developer News. It's meant for internal use, so that our team can produce inspiring, educational, and relevant content for the community.
Note: this guide is primarily aimed at the longer, more comprehensive articles we'll create. It won't be as relevant for quick reference guides, but the underlying principles still apply.
Here are a few things to remember before you start writing or editing an article:
People are busy
So we don't want to waste their time. We want to provide the most valuable content possible.
There's nothing wrong with a long article - we encourage it. Just make it worth your reader's time, and pack it full of info.
The headline rules all
Since people are busy, they'll quickly decide whether they want to read your article - usually based on one thing: the headline.
Spend time crafting a headline that would make YOU want to read that article. More on this below.
So let's get started. Think of this as a checklist that you'll go through each time you write an article. If any of the pieces are missing when you're finished writing, go back through and fill them in.
Step 0: Do your research
Whether you know a little or a lot about the topic, do your research. Spend some time reading up, taking notes, and organizing your thoughts.
Then, when it comes time to write, you'll have plenty to say. As Quincy has shared with us, writer's block usually comes from not knowing enough about the topic.
Step 1: Create a compelling headline
As mentioned above, this is what will draw your readers in. Spend some time on it.
We don't like listicles, click bait, or sensationalist headlines. Sick to matter of fact, clever, "this is what the article is about" type of headlines.
Starting with "How to...", "How I...", or "How x did y..." are often most affective. Just make sure it leaves readers unable to pass that article by.
Note: you should use as many keywords as possible in your H1 and H2 headline elements (this helps with SEO/search).
Step 2: Make it worth their while
Make sure you can write at least 600-1000 words on the topic. If not, consider combining it with another related/larger topic.
Step 3: Choose a relevant, interesting cover image
In addition to the headline, the cover image is the other thing that will draw people in.
You can upload a photo directly from Unsplash under the settings gear (or choose a custom image you've created):
Step 4: Give it a beginning, middle, and end
Organization is important. If readers can't get a good idea of what your story will be about in the opening paragraphs of your article, they might abandon it.
Introduce the topic briefly. Lay out what the article will accomplish and how you're going to do that. Then jump right in.
To help the flow, use headings for main topics and subheadings for smaller topics within those main sections.
In Ghost, this is a heading
This is a sub-heading
Once you're done, compose a quick summary or wrap-up so readers can quickly remember what they just learned and what they should've gotten out of the article.
Step 5: Aim for shorter sentences and paragraphs
It's easy to string together too many words and thoughts and create super long, rambling sentences (and paragraphs). Resist the urge.
Stick to shorter sentences that are easy to break down and digest. Don't use semi-colons - instead, just start a new sentence.
Keep paragraphs at a couple sentences when possible. Single sentence paragraphs are fine.
You can use the Hemingway editor if you need help simplifying your text.
Remember - we want our articles to be easy to read. All this will help.
Step 7: Include images, gists/code snippets, and any other visual aids you need
Many people are visual learners, and a well-placed image and informative code never hurts.
Remember to format your code properly and use syntax highlighting when it's supported. [Do we need more info here?]
If you use images from Unsplash, you don't need to give credit. If you use an image from somewhere else/one that's not creative commons licensed, make sure it's available for use and then appropriately cite that image.
And rather than dropping a URL in with your text (like this: freecodecamp.org), just hyperlink to the page/website/repository like this.
Step 8: Check your grammar, spelling, and punctuation
You may think programmers don't care as much about these things - and perhaps some don't.
But the reality is that bad grammar, incorrect spelling, and improper punctuation make an article harder to read.
Here are a few things (not an exhaustive list) to keep in mind:
- Don't leave out "the" or "a/an" - it really breaks up the flow and makes it sound less natural.
- Don't insert two spaces (accidentally or on purpose) after periods or between words (Ghost lets you do this - be careful).
- Use natural-sounding sentences whenever possible, and use contractions - they help keep things conversational.
- Don't use excessive punctuation!!!! Exclamation points should be used rarely, for emphasis, and only one at a time. Avoid ellipses (...) in general. But use the Oxford comma. :)
- Don't overuse formatting. Use headers and sub-headers when appropriate. Only use bold or italics when you really want to emphasize something (but never use them together - it's harder to read).
- Proof-read for any little spelling errors, misplaced apostrophes (its vs it's - very commonly missed), and grammatical blunders.
Step 9: Add a few tags (and remember that the first is the most important)
Ghost doesn't remind you to add tags, so add it to your list.
The first tag is what will show up above the headline on Developer News. The other tags just help readers discover related articles.
Also, remember to check the page URL and make sure it's not "untitled-15" or something unhelpful like that.
Step 10: Check the tone
Does your article read naturally? Does it sound like you're describing a concept to a friend in a casual setting? If so, more people will read and understand it.
Try to avoid stiff, overly-academic language. Use the simpler word instead of the more difficult one. When in doubt, use a sentence or two to define and explain a new concept/bit of tech.
And once you're all done, step away. And then come back and read it over for typos and missing links.
Other things to note
- Try to avoid profanity - and use common sense. Sex, violence, and profanity don't belong in articles about programming.
- Plagiarism will not be tolerated.
- Please don't change any of the meta data.
- Remember to save as you go with cmd+s or ctrl+s
- Unless your grandparents would understand an acronym, please spell it out.
- Use the "plus" button for supported embedding.