Update: Instead of publishing on Medium, we now run our own self-hosted open-source tool where we're publishing articles to an even larger audience.

You can read more about our move on this forum thread, which includes instructions for how you can apply to become an author, read this style guide.

What follows is for historical purposes if you're curious.

Our open source community runs Medium’s largest technical publication. If you write about development, design, or data science — and are looking for an audience — this is a good place to get published.

1*3fMejdhp9NZORXfOaXVHQw
Our stats from the past 90 days. They’re high enough to break the CSS on the Y axis of Medium’s charts.

freeCodeCamp is an open source community with thousands of contributors, mentors, teachers, and event organizers.

More than a million people learn to code using freeCodeCamp each month, and thousands of us have worked through the 1,200-hour curriculum and gotten their first developer jobs.

1*V0e6SD7Nm-eJD1IIuKcT1g

We’re a nonprofit. You can help us pay for servers and other costs by becoming a supporter.

Here’s what all this means for you as a writer:

  • We won’t plaster your story with advertisements, or put it behind a paywall (or “email wall” or anything — no weird tricks).
  • You can include links to your own blog or service, and even affiliate links, as long as it’s done tastefully and transparently.
  • Your stories are yours. We don’t lay any claim to them. You can cross-post them wherever you want. Other newspapers and websites may even approach you about syndicating them or translating them. That’s fine with us. We just ask that — since we invest a lot of time in editing and promoting your stories — you don’t remove them from our Medium publication once we’ve published them.

Our editors have experience running newspapers and editing technical publications. We’ll read your submission, and if we think it’s promising, we’ll give you candid feedback as to how you can improve it. Then we’ll perform final editing on your story, publish it, then help you publicize it.

Since we launched this Medium publication 18 months ago:

  • we’ve published about 1,000 stories
  • that have received an average of 23,000 views
  • with a median of 6,500 views (that is, half of these stories have received at least 6,500 views)

So if you’re writing about technology, we can help you reach a much larger audience.

Table of Contents

How we evaluate, edit, and publish stories

Note: I’ve hidden the submission instructions, the secret word, and the email address in the text below so that you’ll read all of this. ?

We receive 100+ submissions each week, and are protective of our readers’ time. We seek to only publish stories that are:

  • well written
  • about interesting topics that people haven’t already written about too much
  • relevant to our audience of developers, designers, and data scientists.

If we think your story is a good fit, we’ll add you as a writer to the freeCodeCamp publication and send you an acceptance letter with further instructions.

Then we’ll put your story in the queue to be edited and published. (Here’s our editor handbook if you’re curious about this process). This process may take a while, so we thank you in advance for your patience. You’ll be able to view edits in Medium’s revision history. You will still have full control of your article if you need to make updates.

If we don’t think your story is a good fit for the freeCodeCamp publication, we will send you an email letting you know this. No worries. It won’t negatively affect your ability to get subsequent stories published here.

Note that all our editors have other responsibilities within the open source community, so it may take several days for us to reply to you. But as long as you follow the submission instructions hidden below, we will reply to you.

A quick primer for writing well on Medium

1*3qCQZDqlaC1iq6pkyEybSw

As a writer, you fight a war against indifference. You have to get people to care enough to click through to your story. You have to convince them to take a chance on you.

You have only two weapons against the relentless scroll of news feeds: a headline and an image.

Here’s what a story looks like in Medium’s news feed:

1*iCN5p_9wOJGDuzoAhfe8BQ

Here’s what it looks like on Facebook:

1*K98OoonFq-8q0TBEONae7A

And here’s what it looks like on Twitter:

1*xSJcfQ0tnrXfA7bjXGIcAA

Your headline and opening image are the only things people have to judge your story on. Before they can even read your story’s first paragraph, they must answer a question. It’s the same question that we all ask ourselves every day: is this going to be worth my time?

Your first job as a writer is to choose a headline and image that will make people answer “yes.”

A good headline makes all the difference

Your headline is the most important part of your story. Spend time refining it.

Don’t use clickbait: “You won’t believe this one ridiculously effective headline dark pattern”

Don’t use listicles: “11 outrageous headlines that will compel people to read your Medium story”

Do tell the truth: “Clever but matter-of-fact headline about an interesting topic”

How long should your headline be? HubSpot analyzed 6,000 blog posts and found that stories with 8 to 14-word headlines get more social media shares.

1*NLpfioruotY2jjCWCJtvBA

This said, make sure your headline is 80 characters or fewer. Otherwise, the title will get truncated in news feeds when people share your article on Facebook and Twitter.

Another consideration is how emotional a headline is. The more emotional (positive or negative) a headline is, the more likely people will click it.

Here’s a tool that helps you balance the length and sentiment of your headlines.

1*UQhQRtDVFnpjXmVw9YV5Zg
A screenshot of the tool’s analysis of one of my headlines. Your mileage may vary.

Headlines are traditionally written in “title case.” The Associated Press says to “capitalize the first letter of every word except articles, coordinating conjunctions, and prepositions of three letters or fewer.”

On Medium, I often throw title case out the window and just write headlines like a normal sentence. I even include punctuation as necessary. This format is more conversational, and easier to read.

Don’t break stories into parts. Labels like “part 1” scare people off, because who knows when you’ll get around to writing part 2. And if people encounter “part 2” and they haven’t read part 1, there’s a good chance they just won’t bother reading either. So it’s much better to just publish a single in-depth story.

Arrest with images

The second most important aspect of your story is its featured image.

Medium will automatically make the first image in your article its featured image. This means your article’s og-image meta property will be this image. This image will serve as your story’s ambassador everywhere: social media news feeds, Reddit, Google News — even RSS readers.

You can manually force Medium to treat a specific image as your article’s featured image. While in edit mode, click the image, then:

  • Mac: ⌘ + Opt + 8
  • PC: Ctrl + Alt + 8

Start considering images early in the writing process. And never publish without at least one image. Otherwise your story will be all but invisible in news feeds.

You should break up long stories with images. To paraphrase Mary Poppins, a spoonful of images helps the text go down.

Medium offers four different image widths. Note that these will all look the same on mobile.

Most of the time, you’ll want to stick with column width:

1*akB3u2t_52nVjR3YMk36Kg

If you have a chart that is hard to read when it’s small, go bigger:

1*akB3u2t_52nVjR3YMk36Kg

And if you’re really proud of an image, or if it’s chock full of interesting data, go full-bleed:

1*akB3u2t_52nVjR3YMk36Kg
1*akB3u2t_52nVjR3YMk36Kg

… and then there’s side straddle. Don’t use this size at all, because it makes the text less comfortable to read.

It’s also awkward when you’re done talking about the photo and your text is still pushed to the side.

Yeah. I’m still stuck over here.

Always include a high-resolution image at the top of a story under your headline. This has the following benefits:

  1. When people share your story on Facebook and Twitter, it will be more prominent in news feeds, making people more likely to click on it.
  2. It will look better in Medium’s own news feeds.
  3. Humans are visual creatures, and click on images.

Build momentum with a strong lead

Once your reader clicks through to your story, the trial begins. They’re looking for any excuse to jump back to their news feed. Reading requires a lot more effort than scrolling through cat photos.

Don’t waste time with intros or updates like “This was published on my blog at [blog URL]” or “Update: this has been posted on Hacker News.” You can put these things at the bottom of your story.

Instead, start making points and telling your story immediately.

Establish credibility

Figure out a way to establish your credibility within the first few paragraphs. If you’re a top expert in your field, say so. Don’t assume that people are going to take the time to google you.

“Who you are speaks so loudly I can’t hear what you’re saying.” — Ralph Waldo Emerson

Any achievement or distinction that makes people take you more seriously will help give your readers the impression that “this person knows what they’re talking about.”

Reinforce your credibility throughout your story. Support your arguments with data. Use inline links to (non-paywalled) research.

This isn’t the New England Journal of Medicine. This is Medium. So don’t use footnotes.

Write smart

Good writing is hard. Like any skill, it takes practice. There are no shortcuts to becoming a strong writer.

Do yourself a favor: write what you know.

Have you ever heard the term “writers block?” Writer’s block happens when you don’t know enough about a topic to write about it.

If you have trouble coming up with at least 5 minutes worth of things to say on a topic — or if your story devolves into a list of bullet points — you don’t know enough about it.

The antidote is research. Learning. Going out into the field.

Don’t publish anything you’re not proud of. Medium isn’t a numbers game. It’s a social contract. People follow you. In turn, you show respect for their scarce time.

Good Medium stories don’t come naturally. For every minute of story length, expect to spend at least an hour writing, re-writing, and editing your story.

Attribute your sources

The simplest way to attribute an image is to put the words “Image credit” below an image, and link this text to its original source.

If you’re looking for images you can safely use without permission, check out Pexels, Unsplash, or search Google for images labeled for re-use.

1*Qf6_zsIAM1WYhL93yqoP0g
A Google image search query with the “Labeled for reuse” option selected.

Plagiarism — misrepresenting someone else’s writing as your own — is a serious offense in college, and it’s just as serious on Medium. Always attribute quotes to the people who originally said them. If it’s a multi-line quote, you should use Medium’s pull quotes:

“When you have wit of your own, it’s a pleasure to credit other people for theirs.”
― Criss Jami

You should only use Medium’s pull quotes as a way to highlight actual quotes — not to style your own text.

Showcase your code

Where possible, code should be in text form rather than images. This makes the code more accessible to screen readers, and easier for people to copy and paste.

Medium has a hidden shortcut that will turn text plain text like this:

if (developer === true) {

follow(this.mediumPublication);

}

…into a formatted code block:

if (developer === true) {
  follow(this.mediumPublication);
}

To accomplish this, select the text, then push:

  • Windows: Control + Alt + 6
  • Mac: Command + Option + 6
  • Linux: Control + Alt + 6

You can also start a code block with triple back-ticks. If you type three backticks (```) on a new line, Medium will switch into code input mode.

To highlight code inline, select it, then press the backtick key. This way, you can format text as code freeCodeCamp()right in the middle of a sentence.

You can even embed runnable apps right into Medium. Just in case these don’t render properly in Medium’s mobile apps, I recommend including links below each of the embeds as a fallback.

Paste a CodePen.io URL into Medium, then hit enter:

View my CodePen here.

You can also do this with JSFiddle.net:

View my JSFiddle here.

Sometimes people start lines of code with a $ if they’re terminal commands. Don’t do this. It will confuse beginners and makes it harder to copy and paste commands. Instead, just say something like “Enter the following commands in your terminal.”

Figure out a way to work a link into a sentence. One thing I do not recommend doing is putting a link on its own line and pressing enter. This will create a nice looking preview card, like this:

How to stand on the shoulders of giants
Conquer Not Invented Here Syndrome, then do something new.medium.freecodecamp.com

… but readers often assume these are ads, and don’t even look at them.

The only time I would recommend using this is at the end of your story, if you want to link to further reading.

Underlining text makes it harder to read, so only hyperlink a few words.

Don’t paste URLs directly, like this: ❌ https://www.freecodecamp.com

Instead link to sites like freeCodeCamp mid sentence, like I just did here.

Embed media

You can embed Tweets, YouTube videos, and other media by pasting their URLs into Medium on a new line, then pressing enter.

Use these sparingly, since they may distract your reader from finishing your story.

Explain abbreviations

Don’t use an abbreviation unless the abbreviation is more widely understood than what it stands for. For example, HTTP is more widely recognized than Hypertext Transfer Protocol.

If an abbreviation isn’t already widely understood, and you’re going to refer to it more than a few times, you can define it as an abbreviation by doing this:

“Let’s break the code down into an Abstract Syntax Tree (AST).”

Here I also linked to the Wikipedia article, for readers’ convenience. Don’t assume people will read these external links, though. You still need to define concepts or illustrate them through example.

Avoid defining an abbreviation in your opening paragraphs, as it slows your reader down and makes them less likely to continue reading.

Here’s the very short list of technology abbreviation that you don’t need to define: API, AJAX, BIOS, CPU, CSS, HTML, HTTPS, JSON, LAN, RAM, REST, USB, WWW, XML. For everything else, you should spell it out.

Always spell out short multi-part words like JavaScript and front-end. Don’t shorten them. The brevity isn’t worth the possible confusion.

Look and style

If you want to emphasize something, use bold, but use it sparingly. Italics are harder to read. Don’t bold hyperlinks — the line underneath them already provides enough emphasis.

Don’t use drop caps. They look elegant in old books, but silly on the web.

1*FwHC7L-4Uvgc0jb6OwlCqg
Some old-school-cool print dropcaps

Only use one exclamation point at a time, typically only after exclamations like: Golly gee! Hot dog!

Put commas and periods inside quotes, except when it might confuse a reader (like with variable names or book titles).

In some parts of the world, people put spaces before colons or question marks, like this : example. Don’t do this.

Use English instead of Latin:

  • Use “for example” instead of “E.G.”
  • Use “that is” instead of “I.E.”
  • Use “note that” instead of “N.B.”
  • Instead of ending lists with “etc.” start them with “like”: “Elvis eats food like bread, peanut butter, and bananas.”

According to Google Books, semicolons have been dying a slow death. Let’s put them out of their misery. Just use a period instead, and break clauses into separate sentences.

1*BPlMVGr2WwjLnv-6iTMWvw

Use the Oxford Comma when possible. It makes things easier, clearer, and prettier to read.

Use the Hemingway App. There’s nothing magical about this simple tool, but it will automatically detect widely agreed-upon style issues:

  • passive voice
  • unnecessary adverbs
  • words that have more common equivalents

The Hemingway App will assign a “grade level” for your writing. Even technical stories can pull off a grade level of 6. And they should aspire to.

Most humans are not native English speakers, and the ones who are don’t usually sit around reading Chaucer all day. They want their information accessible and to the point.

Err on the side of breaking long sentences and paragraphs down into shorter ones.

Despite what you may have learned in English composition class, people prefer short paragraphs to “walls of text.”

There’s nothing wrong with single-sentence paragraphs.

Err on the side of creating new paragraphs.

Use contractions. They’ll make your prose seem more conversational. That’s always a plus.

Keep your tense consistent throughout. If you’re talking about something that occurred in past, use past tense.

Also, front-end development (adjective form with a dash) is when you’re working on the front end (noun form with no dash). The same goes with the back end, full stack, and many other compound terms.

Add 5 tags

Medium allows you to add up to five tags to your story. Use them.

People follow specific topics on Medium. The most popular ones are #tech, #life-lessons, #travel, #design, and #startup.

People who follow the tags you use may see your story in their news feed. Tags also make it easier for people to stumble upon your story in search results.

And now that you’ve read this far, here’s how to submit your story to the freeCodeCamp publication: send an email to submit at freecodecamp org. Include the URL for your story on Medium (preferably an unpublished draft) and the word “bananas” so that we’ll know that you have read all this. Only send one story URL per email. There’s no need to add anything further to your email — we just read the stories and judge them based on their own merits.

Publicize your stories on social media

You can share your story on Twitter, Facebook groups, and relevant Subreddits. If you have a mailing list, you can blast it out to your subscribers, too.

You can view your story’s stats in real time. Ask for feedback from your friends and followers. Incorporate this feedback into your story.

Don’t do anything sketchy to promote your story. You will most likely be caught. Sites like Hacker News and Reddit are very good at detecting abnormal voting behavior. This will reflect poorly not just on you, but the entire freeCodeCamp community as well.

Final advice

Remember that when you publish on Medium, you’re asking thousands of people to give you several minutes of their lives. Don’t take your readers for granted.

Before you publish a story, I recommend you sleep, wake up, then proof-read it again.

If you aren’t a native English speaker and are writing in English, ask a native speaker to proof-read your story before submitting it to a publication.

We’re looking forward to reading your submissions. I hope we can help you further improve your stories, and reach a much wider audience.