Thank you for sharing your expertise and your experiences with the developer community.
freeCodeCamp.org/news will help you teach and inspire developers, designers, and data scientists around the world. As one of the most-visited technology sites on the web, freeCodeCamp.org can help you reach thousands of people who will benefit from your wisdom.
Our nonprofit also has a large social media presence, strong accessibility and SEO, and a long reputation as a serious learning resource. All of these will translate into further readership for your articles.
In this style guide, we’ll give you tips for how you can maximize your impact by making your articles as strong as possible.
Substance wins the day
This is not a place for “blog-a-day”-style challenges or stream-of-consciousness observational posts.
Bring your facts. Bring your quotes. Bring your code snippets. Bring your data visualizations.
Years of data show that the more in-depth an article is, the longer people will spend reading it, and the more likely they will share it with their friends.
If you’re not able to write at least 1,500 words about your topic, try doing some more research on it first.
By diving deeper and expanding upon your research, you’ll be able to deliver more insight to your readers.
Package your article properly
People are busy. So you have to capture their attention immediately.
Headlines: The only part of your article that 100% of people will read
Before you start writing your story, spend time crafting a compelling headline. Your entire article will then spring forth from that headline and hook back in to support it.
We’ve found two archetypes that do well: deep technical articles and personal narratives.
Here are a few headline structures we’ve found that work well for deep technical articles:
- "How to fix…"
- "How to build…"
- “How to [task] with [tool]”
- "How [something] works"
- "The [adjective] guide to…"
- “What is a [noun]. In English, please.”
- “What exactly is [noun]?”
- “Why [something] matters.”
- “Learn [something] in N hours”
- "A history of [something]”
- “The story behind [something]”
And here are a few headlines structures that work well for personal narratives:
- "How I [did something]"
- “I [did something]. Here’s what I learned.”
- “How I went from [something] to [something] in N years”
- “Why I started [something]”
- “I’ll never [something] again. Here’s why.”
- “How I [did something] without [something]”
- "Why I don’t [something] anymore"
Add your Cover Images
Once you’ve chosen your clear, informative headline, add a nice cover image. Click the gear in the top-right corner.
Some authors create their own cover art for their article. A free site like Canva.com can help you with this process. (If you want to prevent the edges of your images from getting cut-off when your article is shared on Facebook or Twitter, use an image aspect ratio of 1.91:1.)
If you don’t have an image, you can add a Creative Commons Zero (no attribution needed) image by clicking the Unsplash button in the lower left hand corner.
Set Your post URL
You can set your article’s URL directly. We recommend keeping these short and descriptive like “machine-learning-with-pytorch-tutorial” or “from-trucker-to-developer”.
Once you set your URL and publish it, please don’t change this URL, as it may break any links to the article, resulting in 404 errors.
Add Your Tags
Choose one to five tags for your article. When you start typing, you can choose existing tags from the dropdown.
These tags will make it easier for readers to discover your articles through search and when browsing tags.
The first tag you choose is the most important, and it will show up above your article, like this:
Please don’t change anything below the Tags section. /news has sane default values for these.
Tips for writing an article people will actually read
Grammar, spelling, and formatting do matter
It’s easier to read articles that are clear and properly formatted. Here are some tips to make your articles as readable as possible:
- Keep it simple. Use simple, straightforward language whenever possible.
- Use short sentences. Break down longer sentences into shorter ones. This helps people read faster and understand better.
- Use short paragraphs. Break down longer paragraphs into one or two sentence paragraphs. Walls of text will make your readers abandon your article or switch to “skimming” mode.
- Clean up the punctuation. Too many exclamation marks can be distracting! Semi-colons are rarely necessary; just use a period instead. And ellipses are... well... usually a bit much.
- Use headers to structure your text. /news gives you both large and small headers for your toolkit. Use large headers for main topics, and smaller sub-headers for sections within those topics.
- Remove abbreviations. They make articles harder to understand. Spell out any acronym that isn’t well-known. Turn Latin expressions like “e.g.” into “for example” and “… etc.” into “like ...”
Proof-read your article. Then proof-read it again.
Some authors write quickly so they can get their ideas down on paper. Others authors do all their research before they write a single word.
Whatever your writing process, be sure to step away from your article, and come back with a fresh pair of eyes.
Read your article over again. Then read it out loud. You'll be amazed at the little errors, misspellings, and awkward phrases you catch.
Add syntax highlighting to your code
You can create a code block by typing three backticks (```), followed by hitting the spacebar.
You can even specify the programming language for which you want syntax highlighting.
Stay on topic
Your readers’ time is finite. Help your readers to get as much value out of your articles as possible before they have to move on with their lives.
Keep your deep technical articles as step-by-step as possible
- Write a concise introduction that tells readers what they’ll accomplish
- Use a numbered list like this one to indicate steps
- Pack in as much detail as you can
- Close out by reminding readers what they just accomplished
Tell your personal stories like a novel
Even though your headline will probably give away the ending of your story (“How I went from overnight trucker to software developer in 2 years”) you can still tell it like a novel.
Rather than jumping around through time, start at the beginning and paint a picture of your life before and after your journey.
See if you can frame your story around a central conflict. For example, overcoming:
- immigration challenges
- brutal job interviews
- learning disabilities
- age discrimination
- or just procrastination (the most common challenge)
Conflict is central to narrative. Books and movies are interesting because of the conflict between characters, their environment, and even within themselves.
Write longer comprehensive articles instead of multi-part articles
We’ve observed time and time again that people will not bother reading the second, third, or nth part in a series if they haven’t read all the previous parts.
At the same time, we’ve seen that very long, in-depth articles work surprisingly well. People will bookmark your article or share it on social media so they can come back to it.
When people see that an article is long, they’ll often assume the article is serious and comprehensive. This inspires people to slow down and really spend time reading your article. Many people will even open up their code editor and code along at home.
Keep it as G-rated as possible
The freeCodeCamp community is mostly adults, but there are some children here as well.
If you’re writing about a topic like sexual harassment, there’s no real way to keep it “G-rated.” But in most circumstances, this is possible.
Try not to use profanity unless it’s in a direct quote, and steer clear of potentially offensive memes.
Finally, if an article seems to violate freeCodeCamp’s code of conduct, we will immediately delete it. But we will save a copy of it and send it to you for your own records, so that you don’t lose your work.
Acceptable ways you can self-promote in your articles
freeCodeCamp.org is a donor-supported nonprofit. We don’t want anyone to get the impression that we do “paid placement” (we don’t) as this could discourage people from donating to us.
At the same time, we totally understand that you may want to publicize your latest book, course, SaaS application, or other product.
We ask that you keep this as tasteful as possible. It is perfectly fine to talk about your product at the end of your article.
Don’t open your article with a link to your product, as this looks spammy.
Also note that we do not allow branded accounts. We forbid any sort of ghost writing. We will not transfer articles from one employee to another.
And please - do not publish stories on behalf of other people who have not yet earned a /news Author Account.
A note on cross-posting
There are already a lot of open platforms where you can cross-post your blog articles.
With /news, instead of cross-posting, you can anthologize several of your past articles on a similar topic (such as "Visual Studios Plugins" or "Advanced Bash Commands") into a single longer article.
We can then publish and publicize that article, and encourage people to go to your blog to read more such articles.
Note that for your own SEO purposes - unlike most popular websites - all links on /news are
rel="doFollow". This means that yes - each page you link to (including your own blog) will get a boost in Google rankings.
Finish up the process
Once you’re confident your story is ready for readers, you can hit publish.
Our editorial team will quickly go through and make edits to further strengthen your article.
The main things we care about are the headline and the opening paragraphs. If we notice any text formatting issues or grammatical errors, we’ll correct them too.
In some circumstances, if we think you may have published an article by mistake before it was ready, we may un-publish it and email you about it.
Other helpful tips
Did you know you can use GitHub-flavored Markdown to compose your articles?
You can paste markdown into /news and it will be instantly converted to rich text.
You can also type markdown syntax at the beginning of a line - say # or ## for headings, or * for a bulleted list - then start typing. The text will change to your specified format.
Go easy on the embeds
You can embed things like tweets and YouTube videos if you want. Just click the + icon at the beginning of a new line, and you can choose from a variety of embedding tools.
This said, we encourage you to use these sparingly, for three reasons:
- The embeds make a call to an external service, such as twitter, which may slow down the experience
- Many people who read /news are doing so using screen readers. A large portion of the developer community lives with visual impairments (or completely blindness). Embeds are less accessible than text.
- Each /news article has an Accelerated Mobile Pages version and the embeds may not show up properly there.
How to apply for an author account
If you don't have a /news author account yet, you can apply for one.
Since we are focused on quality over quantity, we are being quite selective.
But if we do accept your application, here's what will happen:
- We will email a link to set up your provisional contributor account.
- You can then create drafts, and email us links to these drafts for editorial feedback.
- Once we publish one of your stories, we'll convert your account into a full-blown author account. We'll also give you full access to /news Google Analytics.
You can apply for an author account here.
Thank you for sharing your insights with the developer community.
We hope this guide will help you write better articles so the entire community can benefit from your insight.
— The freeCodeCamp Editorial Team