Thank you for sharing your expertise and your insights with the developer community.
Our publication 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, SEO, and an established reputation as a serious learning resource. All of these will translate into more 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,000 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. How do you do that? With a compelling headline.
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 contributors 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”.
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. Our publication 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 sub-headings to structure your text. Our publication gives you both large and small heading sizes for your toolkit. Use large headings for main topics, and smaller sub-headings for sections within those topics.
- Don't use excessive bold, italics, or both. Too much text formatting makes it hard to read. Especially if you use both bold and italics together. Use bold and italics separately, and sparingly.
- 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 contributors write quickly so they can get their ideas down on paper. Other contributors 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.
No cross-posting, please.
Cross-posting is ineffective. If you want a lot of people to read your article, just focus your efforts on a single publication – whether that's freeCodeCamp's publication, or your own blog, or an online magazine.
You can, however, take some of your personal blog posts on a similar topic (such as "Visual Studios Plugins" or "Advanced Bash Commands") and anthologize them into a single, longer freeCodeCamp article.
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 have a one-sentence call-to-action for 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. And we will not transfer articles from one employee to another.
And please – do not write stories on behalf of other people who have not yet earned their contributor account.
Note that for your own SEO purposes – unlike most popular websites – all links on our publication are
rel="doFollow". This means that yes – each page you link to (including your own blog) will get a boost in Google rankings. Please keep this in mind and don't over-do it.
Finishing up the process
Once you’re confident your story is ready for readers, email a link to your draft to firstname.lastname@example.org. Our editorial team will quickly go through and make edits to further strengthen your article before publishing it.
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.
If we still think your article needs significant work, we will tell you so, and you can then re-submit it once you've made those changes.
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 the publication 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 publication article has an Accelerated Mobile Pages version, and the embeds may not show up properly there.
How to apply for a contributor account
If you don't have a contributor account yet, you can apply for one 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