Last year I built Top Medium Stories — a website that showcases the Medium’s top stories of all time. This is the tale of how a lone developer scraped thousands of stories and hitting seemingly fatal roadblocks.

Spoiler alert: Life finds a way. You can check out the leaderboard — updated daily — at TopMediumStories.com.

Why did I make this?

As a long-time reader on Medium, I’ve always been curious what the most popular stories were. While the personalized feed and topic pages surface many great stories, just as many slip through the cracks.

Driven to unearth the gems buried in Medium’s annals, I set a new goal in early 2017: I was going to find the most popular stories of all time on Medium and share them with the rest of the world.

My goal culminated in me publishing my list of the Top Medium Stories By Year.

I compiled the stories manually, which was a grueling task. Over the period of a week, I visited every top stories page since September 10, 2014 (when the top stories feature debuted). To find even earlier stories, I dug through publication archives using the Wayback Machine to fetch ancient copies of Medium pages.

I built a massive spreadsheet of every story I found. It was a ton of mind-numbing work, but I was proud of the result.

A small section of the colossal spreadsheet ?

But my feeling of pride was short-lived, as the list became quickly outdated. I wanted to keep it up-to-date, but doing so manually was impossible.

Then, something dawned on me. I had already determined the manual steps to collect data the first time. There was was no reason why I couldn’t just automate those steps with code. Thus, I decided to turn the list into a dynamic website.

Automating data collection

To automate the manual steps described above, I wrote a web scraper using Python Scrapy.

The scraper crawls through every top stories page since September 10, 2014 and tosses any story it sees into a Python dictionary. The dictionary is then sorted by the number of claps each story received and written to a JSON file. (Claps are Medium’s equivalent of a “like” or an “upvote” and readers can give a story up to 50 claps.)

Here’s a snippet of the JSON file:

[  “We fired our top talent. Best decision we ever made.”,   {    “recommends”: 79000.0,     “pub_url”: “https://medium.freecodecamp.org",     “author”: “Jonathan Sol\u00f3rzano-Hamilton”,     “image”: “https://cdn-media-1.freecodecamp.org/images/1*4hU3Xn7wunA81I3v17JIrg.jpeg",     “year”: “2017”,     “story_url”: “https://medium.freecodecamp.org/we-fired-our-top-talent-best-decision-we-ever-made-4c0a99728fde",     “pub”: “freeCodeCamp”,     “author_url”: “https://medium.freecodecamp.org/@peachpie"  }],...

Before building the scraper, I checked Medium’s robots.txt file to verify that I wasn’t violating any policies. I also set the scraping speed very slow (2 seconds between each request), so the scraper wouldn’t hammer Medium’s servers.

Converting the data to HTML

The next step was transforming the JSON file into HTML to display the stories on a web page.

I installed BeautifulSoup to do this. First, I constructed an HTML template with empty tables and rows. Then, I wrote a script that uses BeautifulSoup to populate the template from the JSON file.

With a basic HTML file containing all the stories I want to display, it was time to create the actual website.

Building a kickass website

When planning the website, I had three goals in mind:

1. Minimal and elegant design

The design language is centered around plenty of whitespace and high-contrast text. This way, the focal point is on the stories its trying to highlight, not on the aesthetics of the website itself.

I also added a “Compact” view mode, which hides feature images from the website. This allows readers to skim through the list with ease.

“Compact” mode

2. Fast

The first version of the website was quite sluggish. This is because it was trying to load hundreds of feature images at once.

To solve this issue, I used “lazy loading.” When you land on the website, only the first 50 stories under “All” are loaded. If you want to see more stories, you have to click on “Load more.” This design pattern drastically reduces the initial loading time.

Also, to make navigation feel more responsive, I designed this website as a single-page web app. When you click on a button, you don’t navigate to another HTML page. Instead, jQuery switches the view instantaneously.

Responsive navigation and lazy loading in action

3. Lightweight

To keep the website light, I chose to forgo most popular frontend libraries. I didn’t use Bootstrap, and I kept JavaScript/jQuery usage to a minimum.

Taking a glance at the project repo reveals a very minimal setup. A few HTML files, a CSS file, a couple scripts, and a handful of data files.

As a result, the website doesn’t have many moving parts and dependencies. It’s very simple to maintain and debug.

Testing and launching

I shared the prototype with a couple of friends and asked them to rip it apart. Using their feedback, I iterated on the design twice. Then, I launched on Product Hunt.

I could barely sleep that night. I still remember constantly refreshing the page checking for new comments until I passed out from exhaustion.

The next morning, I scrambled out of bed and clawed open my computer. I couldn’t believe my eyes! Top Medium Stories was at the top of Product Hunt’s homepage. At the end of the day, it was awarded the #2 product of the day.

_[Product Hunt page for Top Medium Stories](https://www.producthunt.com/posts/top-medium-stories" rel="noopener" target="blank" title=")

The sudden death of Medium Top Stories

The Product Hunt launch exceeded my wildest expectations, and I was on cloud nine for a long time. But I knew I wasn’t done until I shared my project on Medium. I started this post half a year ago and I finally finished it a few weeks ago. I was beyond excited to publish it.

Before submitting, I decided to run the data collection script one more time to update the website.

The script failed catastrophically.

“No big deal. Either Medium has an outage or my internet isn’t working,” I thought. But I was so wrong. When I realized what actually happened, I slumped into my chair and dragged my fingers down my face in frustration.

I kid you not, two days prior Medium had removed the top stories page from their website. They scuttled the very page my scraper depended on to function!

I emailed Medium promptly, asking them to consider reverting the top stories page. I didn’t get the response I was looking for.

But I didn’t blame them. My website wasn’t officially supported — they weren’t obligated to do anything. Even if they didn’t make this particular change, eventually one of their updates would break my website. It was inevitable.

I felt hopeless. Since the website couldn’t be updated anymore, it was no more than a static list that was soon to be obsolete. In my mind, Top Medium Stories was dead on arrival.

The sprouts of new life

For a while, I worked on other stuff and didn’t look at Top Medium Stories at all. But I couldn’t stop thinking about the unfinished story of the website. I wanted to publish a postmortem — even if it didn’t have a happy ending. It felt like a good way close out the project.

I closed the article with:

“So, I hope you enjoyed reading about Top Medium Stories. It was an amazing experience and I’m proud of what I made — I’m sorry it had to end this way. There will always be things you can’t predict or control, and they can wipe away your work in a heartbeat. That’s life.”

As I stared at my finished draft, I realized something. I hate sad endings.

Suddenly, my eyes locked on that same JSON blob I mentioned earlier.

[  “We fired our top talent. Best decision we ever made.”,   {    “recommends”: 79000.0,     “pub_url”: “https://medium.freecodecamp.org",     “author”: “Jonathan Sol\u00f3rzano-Hamilton”,     “image”: “https://cdn-media-1.freecodecamp.org/images/1*4hU3Xn7wunA81I3v17JIrg.jpeg",     “year”: “2017”,     “story_url”: “https://medium.freecodecamp.org/we-fired-our-top-talent-best-decision-we-ever-made-4c0a99728fde",     “pub”: “freeCodeCamp”,     “author_url”: “https://medium.freecodecamp.org/@peachpie"  }],...

And I had a revelation. I didn’t need the top stories page to update the website. Instead, I could visit each url in the JSON file and pull the data directly from the story’s webpage.

To fetch new stories, I could scrape the new Popular on Medium page, which would give me the top stories published recently.

Having refactored my code, I realized something: it is possible that not every single popular new story will end up being showcased on the Popular on Medium page. So if you happen to read a story that you think should be on Top Medium Stories but isn’t, please let me know. Just send the story’s url to michaeldeng18@gmail.com, and I’ll add it in right away. Together, we can ensure the leaderboards are as comprehensive as possible.

There is always the risk that Medium might one day restrict scraping completely, or even release their own ranking of stories. Either of these changes could make Top Medium Stories obsolete.

But in the meantime, I will continue maintaining Top Medium Stories, the best website for discovering awesome stories.

If by this point you still have not seen Top Medium Stories, go check it out! It’d make me very happy if the site helps you find extraordinary stories that you would’ve otherwise never stumbled upon.

Thanks for reading!

In this article, I’ll discuss how you can create a table of contents for your Medium post, and I’ll show you how I built the feature.

Table of Contents

• Get The URL
• Generate Your Table Of Contents
• Design
• Development
• Get the source

Many of you have probably seen this post about how to link to parts of your Medium article. You may have also seen this chrome extension, which makes the process simpler.

Well, you can do one better. This is how to create a table of contents for your Medium article, automatically.

1. Get The URL

First, you need the URL of your Medium article. If it has been published, just grab the link from your address bar

If you are still writing, click the “share” button in the top right corner, and copy the link from there

2. Generate Your Table Of Contents

Now the easy bit. Go to www.mediumtoc.com and paste your URL in the input bar, and click “go.”

Then it should give you your contents, which you can copy and paste into your medium article!

You can see this in action at the top of this post.

How I Built This

Design:

I first designed the website in Sketch. I chose to take some design cues from the Medium website, with a serif font for the heading, and I also used the same button design.

I chose to use a https://material.io/guidelines/components/text-fields.html input bar, as the design is functional and minimalistic, the style I was going for.

Development:

The architecture of this app is largely based on the JAM stack. This is based on the idea of having client side Javascript, reusable API’s, and prebuilt markup. It allows sites to go on CDNs.

The sites architecture is:

Front End: React and Preact (a lightweight virtual DOM implementation) in production

Back End: Express running on Now, although I plan to migrate to AWS Lambda, as there is only 1 API endpoint. The back end scrapes the headings from the Medium article and returns their links.

Front End Hosting / CDN: The site runs on Netlify, which has free SSL integration, and automatically deploys from the master branch on GitHub.

If anyone is interested in any of these topics, leave a comment and I will write more about them!

The website was designed and developed over the course of two days. The first day was focused on the back end of the site, and the design. The second day was the development. There are only 4 react components, and I chose not to use redux, as there is not very much changing in the state.

Get the source!

This is open source, so you can get all the code on github.com/adamisntdead/medium-toc. ✨

Big thanks to the freeCodeCamp community for their wonderful publication!

If you liked this article, please leave an applause! ? Want more articles like this? Follow me.

Medium has a large amount of content, a large number of users, and an almost overwhelming number of posts. When you try to find interesting users to interact with, you’re flooded with visual noise.

I define an interesting user as someone who is from your network, who is active, and who writes responses that are generally appreciated by the Medium community.

I was looking through the latest posts from users I follow to see who had responded to those users. I figured that if they responded to someone I’m following, they must have similar interests to mine.

The process was tedious. And that’s when I remembered the most valuable lesson I learned during my last internship:

Any tedious task can and should be automated.

I wanted my automation to do the following things:

1. Get all the users from my “Followings” list
2. Get the latest posts of each user
3. Get all the responses to each post
4. Filter out responses that are older than 30 days
5. Filter out responses that have less than a minimum number of recommendations
6. Get the username of the author of each response

Let’s start pokin’

I initially looked at Medium’s API, but found it limiting. It didn’t give me much to work with. I could only get information about my account, not on other users.

On top of that, the last change to Medium’s API was over a year ago. There was no sign of recent development.

I realized that I would have to rely on HTTP requests to get my data, so I started to poke around using my Chrome DevTools.

The first goal was to get my list of Followings.

I opened up my DevTools and went on the Network tab. I filtered out everything but XHR to see where Medium gets my list of Followings from. I hit the reload button on my profile page and got nothing interesting.

What if I clicked the Followings button on my profile? Bingo.

Finding the link that lists a user’s followings

Inside the link, I found a very big JSON response. It was a well-formatted JSON, except for a string of characters at the beginning of the response: ])}while(1);</x>

I wrote a function to clean that up and turn the JSON into a Python dictionary.

import json

def clean_json_response(response):    return json.loads(response.text.split('])}while(1);</x>')[1])

I had found an entry point. Let the coding begin.

Getting all the users from my Followings list

To query that endpoint, I needed my User ID (I know that I already had it, but this is for educational purposes).

While looking for a way to get a user’s ID, I found out that you can add ?format=json to most Medium URLs to get a JSON response from that page. I tried that out on my profile page.

Oh look, there’s the user ID.

])}while(1);</x>{"success":true,"payload":{"user":{"userId":"d540942266d0","name":"Radu Raicea","username":"Radu_Raicea",...

I wrote a function to pull the user ID from a given username. Again, I had to use clean_json_response to remove the unwanted characters at the beginning of the response.

I also made a constant called MEDIUM that contains the base for all the Medium URLs.

import requests

MEDIUM = 'https://medium.com'

def get_user_id(username):

    print('Retrieving user ID...')

    url = MEDIUM + '/@' + username + '?format=json'    response = requests.get(url)    response_dict = clean_json_response(response)    return response_dict['payload']['user']['userId']

With the User ID, I queried the /_/api/users/<user_id>/following endpoint and got the list of usernames from my Followings list.

When I did it in DevTools, I noticed that the JSON response only had eight usernames. Weird.

After I clicked on “Show more people,” I saw what was missing. Medium uses pagination for the list of Followings.

Medium uses pagination for Followings list

Pagination works by specifying a limit (elements per page) and to (first element of the next page). I had to find a way to get the ID of that next element.

At the end of the JSON response from /_/api/users/<user_id>/following, I saw an interesting key.

..."paging":{"path":"/_/api/users/d540942266d0/followers","next":{"limit":8,"to":"49260b62a26c"}}},"v":3,"b":"31039-15ed0e5"}

From here, writing a loop to get all the usernames from my Followings list was easy.

def get_list_of_followings(user_id):

    print('Retrieving users from Followings...')        next_id = False    followings = []

    while True:

        if next_id:            # If this is not the first page of the followings list            url = MEDIUM + '/_/api/users/' + user_id                  + '/following?limit=8&to=' + next_id        else:            # If this is the first page of the followings list            url = MEDIUM + '/_/api/users/' + user_id + '/following'

        response = requests.get(url)        response_dict = clean_json_response(response)        payload = response_dict['payload']

        for user in payload['value']:            followings.append(user['username'])

        try:            # If the "to" key is missing, we've reached the end            # of the list and an exception is thrown            next_id = payload['paging']['next']['to']        except:            break

    return followings

Getting the latest posts from each user

Once I had the list of users I follow, I wanted to get their latest posts. I could do that with a request to [https://medium.com/@<username>/latest?forma](https://medium.com/@username/latest?format=json)t=json

I wrote a function that takes a list of usernames and returns a list of post IDs for the latest posts from all the usernames on the input list.

def get_list_of_latest_posts_ids(usernames):

    print('Retrieving the latest posts...')

    post_ids = []

    for username in usernames:        url = MEDIUM + '/@' + username + '/latest?format=json'        response = requests.get(url)        response_dict = clean_json_response(response)

        try:            posts = response_dict['payload']['references']['Post']        except:            posts = []

        if posts:            for key in posts.keys():                post_ids.append(posts[key]['id'])

    return post_ids

Getting all the responses from each post

With the list of posts, I extracted all the responses using https://medium.com/_/api/posts/<post_id>/responses

This function takes a list of post IDs and returns a list of responses.

def get_post_responses(posts):

    print('Retrieving the post responses...')

    responses = []

    for post in posts:        url = MEDIUM + '/_/api/posts/' + post + '/responses'        response = requests.get(url)        response_dict = clean_json_response(response)        responses += response_dict['payload']['value']

    return responses

Filtering the responses

At first, I wanted responses that had gotten a minimum number of claps. But I realized that this might not be a good representation of the community’s appreciation of the response: a user can give more than one clap for the same article.

Instead, I filtered by the number of recommendations. It measures the same thing as claps, but it doesn’t take duplicates into account.

I wanted the minimum to be dynamic, so I passed a variable named recommend_min around.

The following function takes a response and the recommend_min variable. It checks if the response meets that minimum.

def check_if_high_recommends(response, recommend_min):    if response['virtuals']['recommends'] >= recommend_min:        return True

I also wanted recent responses. I filtered out responses that were older than 30 days using this function.

from datetime import datetime, timedelta

def check_if_recent(response):    limit_date = datetime.now() - timedelta(days=30)    creation_epoch_time = response['createdAt'] / 1000    creation_date = datetime.fromtimestamp(creation_epoch_time)

    if creation_date >= limit_date:        return True

Getting the username of the author of each response

Once I had all the filtered responses, I grabbed all the authors’ user IDs using the following function.

def get_user_ids_from_responses(responses, recommend_min):

    print('Retrieving user IDs from the responses...')

    user_ids = []

    for response in responses:        recent = check_if_recent(response)        high = check_if_high_recommends(response, recommend_min)

        if recent and high:            user_ids.append(response['creatorId'])

    return user_ids

User IDs are useless when you’re trying to access someone’s profile. I made this next function query the /_/api/users/<user_id> endpoint to get the usernames.

def get_usernames(user_ids):

    print('Retrieving usernames of interesting users...')

    usernames = []

    for user_id in user_ids:        url = MEDIUM + '/_/api/users/' + user_id        response = requests.get(url)        response_dict = clean_json_response(response)        payload = response_dict['payload']

        usernames.append(payload['value']['username'])

    return usernames

Putting it all together

After I finished all the functions, I created a pipeline to get my list of recommended users.

def get_interesting_users(username, recommend_min):

    print('Looking for interesting users for %s...' % username)

    user_id = get_user_id(username)

    usernames = get_list_of_followings(user_id)

    posts = get_list_of_latest_posts_ids(usernames)

    responses = get_post_responses(posts)

    users = get_user_ids_from_responses(responses, recommend_min)

    return get_usernames(users)

The script was finally ready! To run it, you have to call the pipeline.

interesting_users = get_interesting_users('Radu_Raicea', 10)print(interesting_users)

_Image credit: [Know Your Meme](http://knowyourmeme.com/photos/185885-success-kid-i-hate-sandcastles" rel="noopener" target="blank" title=")

Finally, I added an option to append the results to a CSV with a timestamp.

import csv

def list_to_csv(interesting_users_list):    with open('recommended_users.csv', 'a') as file:        writer = csv.writer(file)

        now = datetime.now().strftime('%Y-%m-%d %H:%M:%S')        interesting_users_list.insert(0, now)                writer.writerow(interesting_users_list)

interesting_users = get_interesting_users('Radu_Raicea', 10)list_to_csv(interesting_users)

The project’s source code is on GitHub.

If you don’t know Python, go read TK’s Learning Python: From Zero to Hero.

If you have suggestions on other criteria that make users interesting, please write them below!

In summary…

• I made a Python script for Medium.
• The script returns a list of interesting users that are active and post interesting responses on the latest posts of people you are following.
• You can take users from the list and run the script with their username instead of yours.

Check out my primer on open source licenses and how to add them to your projects!

For more updates, follow me on Twitter.

freeCodeCamp is now the largest technology publication on Medium. And as its sole editor, I get way more high-quality story submissions than I have time to edit and publish.

This means that I’m the biggest bottleneck — between all the developers, designers, and data scientists writing these amazing stories — and a growing audience that’s eager to read them.

Even though freeCodeCamp.org reaches millions of people each month through Medium, YouTube, and our coding platform, we’re a small donor-supported nonprofit. We lack the resources to hire professional editors.

This said, a lack of resources hasn’t stopped us in other areas. We have thousands of volunteers running local study groups, contributing to open source projects, and moderating forums and chatrooms.

If you have experience editing a newspaper, academic journal, magazine, or blog, and are able to contribute a few hours of your time each week to this publication, we should talk. ? Read our publication guide, then reach out to me.

You’ll learn a ton about technology in the process, and help a community that has published 1,000+ free (and ad-free) articles. And together, we’ll be able to maintain our current high standards while publishing a lot more stories for everyone to read.

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.

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.

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
• A quick primer for writing well on Medium
• A good headline makes all the difference
• Arrest with images
• Build momentum with a strong lead
• Establish credibility
• Write smart
• Attribute your sources
• Showcase your code
• Make links look natural
• Embed media
• Explain abbreviations
• Look and style
• Add 5 tags
• Publicize your stories on social media
• Final advice

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

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:

Here’s what it looks like on Facebook:

And here’s what it looks like on Twitter:

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.

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.

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:

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

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

… 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.

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.”

Make links look natural

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.

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.

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.

According to SimilarWeb, Medium had more than 84 million visits last month.

Medium isn’t going away any time soon. So instead, let’s focus on how you can write stories that readers will find helpful here in 2017.

I pulled down the top 252 stories of 2016 — all of which had at least 2,500 recommendations from Medium’s readers — and analyzed the dataset.

To put things in perspective, writers published 7,500,000 stories on Medium last year. So this dataset represents the most popular 0.00336% stories of 2016.

Together, these 252 stories racked up 1,033,961 recommendations. That’s a lot of green hearts.

Here are some things I learned from my time with this dataset that can help you reach a wider audience for your writing in 2017.

Insight #1: You don’t have to be famous to do well on Medium

169 different writers published one of these top-252 stories. Some of those writers had multiple top stories.

Here are the people who wrote more than one top-252 story:

+----------------------+---------+---------------------+|         Name         | Stories | Mostly writes about |+----------------------+---------+---------------------+| Benjamin Hardy       |      17 | Self Improvement    || Quincy Larson        |      16 | Technology          || Jon Westenberg       |      13 | Life                || Darius Foroux        |       7 | Life Lessons        || Julie Zhuo           |       4 | Design              || Sarah Cooper         |       4 | Satire              || Jonathan Z. White    |       3 | Design              || Bill Sourour         |       3 | Programming         || Jessica Semaan       |       3 | Life Lessons        || Jason Fried          |       3 | Business            || Thomas Oppong        |       3 | Life                || Larry Kim            |       3 | Productivity        || Gary Vaynerchuk      |       3 | Entrepreneurship    || Chris Dixon          |       3 | Technology          || Amanda Rosenberg     |       3 | Humor               || Andy Raskin          |       2 | Marketing           || Charles Scalfani     |       2 | Programming         || Chris Messina        |       2 | Design              || James Altucher       |       2 | Life                || John Fawkes          |       2 | Productivity        || John Saito           |       2 | Design              || Marc Cenedella       |       2 | Business            || Tobias Van Schneider |       2 | Design              |+----------------------+---------+---------------------+

The only person on this list whom I’d heard of before reading their work here on Medium is Chris Dixon, a well-known tech blogger.

You may recognize some of these names if you’re in their field, but I doubt you’d recognize these people if you ran into them at the super market. They may be “internet famous” but they’re a far cry from household names.

If you can write consistently useful stories and gradually build a following, you can crack this list, too.

Insight #2: Medium is a serious place

Here are the most common tags among these top 252 stories:

+------------------+-------------+------------+|       Tag        |   Stories   | Percentage |+------------------+-------------+------------+| Startup          |          62 | 25%        || Tech             |          47 | 19%        || Life Lessons     |          45 | 18%        || Entrepreneurship |          37 | 15%        || Design           |          34 | 13%        || Self improvement |          31 | 12%        || Productivity     |          26 | 10%        || Politics         |          21 | 8%         || Programming      |          18 | 7%         || UX               |          18 | 7%         || JavaScript       |          10 | 4%         || Web Development  |          10 | 4%         |+------------------+-------------+------------+

The following topics — which are the basis of most popular magazines — occurred zero times:

• sports
• fitness
• cars
• weddings
• gaming
• homes
• food
• celebrities
• finance

“Humor” occurred 9 times, and “satire” 5 times. But that’s about it.

It seems that most people read Medium to:

• get motivated
• learn more about their field

Judging by this dataset, the stereotype of Medium’s readership as developer-designer-hustlers isn’t all that far from the truth.

Insight #3: You should definitely try to get your story into a publication

+----------------------+---------+-----+----------------+|      Publication     | Stories |  %  |     Topic      |+----------------------+---------+-----+----------------+| Not in a publication |      67 | 26% | n/a            || The Mission          |      52 | 21% | Productivity   || Free Code Camp       |      30 | 12% | Technology     || Signal VS Noise      |       7 | 3%  | Startups       || Hi My name is Jon    |       4 | 2%  | Jon Westenberg || Slackjaw             |       4 | 2%  | Humor          || Startup Grind        |       4 | 2%  | Startups       || Year of Looking Glass|       4 | 2%  | Julie Zhuo     || The Startup          |       4 | 2%  | Startups       || Be Yourself          |       3 | 1%  | Life           || Art of Practicality  |       3 | 1%  | Productivity   || Conquer Corp America |       3 | 1%  | Productivity   || Personal Growth      |       2 | 1%  | Productivity   || The Coffeelicious    |       2 | 1%  | Startups       || Development Set      |       2 | 1%  | Education      || UX Design            |       2 | 1%  | UX             |+----------------------+---------+-----+----------------+

A vast majority of the top 252 stories were published in one of Medium’s publications.

If you think about this for a moment, it makes perfect sense. These stories showed up not only in the news feeds of the readers who followed their authors, but also readers who followed the publication.

And some of these publications have a lot of followers.

Insight #4: Personal stories do better

Here’s a lexical analysis of the most common words in the titles of the top 252 stories. I’ve filtered out stop words like “the” and “of.”

+-------+-----------------+| Count |      word       |+-------+-----------------+|    42 |  you            ||    39 |  i              ||    30 |  how            ||    24 |  your           ||    16 |  about          ||    15 |  my             ||    14 |  people         ||    14 |  life           ||    12 |  why            ||    11 |  design         ||    10 |  me             ||     9 |  trump          ||     9 |  read           ||     9 |  learn          ||     8 |  time           ||     7 |  new            ||     7 |  letter         ||     6 |  yourself       ||     6 |  live           ||     6 |  job            ||     6 |  better         ||     5 |  year           ||     5 |  white          ||     5 |  silicon valley ||     5 |  stop           ||     5 |  never          ||     5 |  most           ||     5 |  f***           ||     5 |  free           ||     5 |  apps           ||     4 |  world          ||     4 |  work           ||     4 |  websites       ||     4 |  web            ||     4 |  successful     ||     4 |  smarter        ||     4 |  open           ||     4 |  javascript     ||     4 |  hard           ||     4 |  guide          ||     4 |  f******        ||     4 |  code           ||     3 |  wish           ||     3 |  technology     ||     3 |  startup        ||     3 |  secret         ||     3 |  quit           ||     3 |  productivity   ||     3 |  programming    ||     3 |  powerful       ||     3 |  medium         ||     3 |  love           ||     3 |  future         ||     3 |  development    ||     3 |  developer      ||     3 |  designer       ||     3 |  career         ||     3 |  business       |+-------+-----------------+

The words “you” and “I” were by far the most common, which suggests that addressing the reader directly as an individual person is a better writing strategy than writing in third person.

The most common words that fell outside of the 100 most common English language words were “life” and “design.”

Speaking of English, all but three of the top 252 stories were written in English.

Insight #5: You don’t need to cuss to get people’s attention

Many people complain about the abundance of profanity in Medium headlines.

While it’s certainly present, the “F” word and its variants only occurred 13 times in top-252 headlines, and the “S” word only occurred 3 times.

Insight #6: “Listacles” still exist, but they don’t dominate Medium

Only 23 of the top 252 stories were explicitly “listacles” — bullet-point-driven stories.

These stories have headlines that follow the pattern of “[number] things you should do before you [time].”

Full disclosure: one of these listacles is my story about Linux turning 25.

But overall, I’d say the decline of listacles is a good thing.

My personal advice to writers is to focus on stories that dive deep into a single topic.

Insight #7: 7 minutes is still an ideal story length

The top 252 stories averaged 6.7 minutes in length — the same length that Medium’s data science team determined was optimal back in 2014.

Insight #8: Include images.

Only 16 of the top stories didn’t have any images.

The median number of images a story included was 3.

Don’t worry about over-doing it with images, either. 11% of stories used 10 or more images, and two of them used more than 50 images.

Insight #9: It definitely helps to have a lot of followers

The median number of followers these authors had as of year’s end was 6,809.

Even if you don’t yet have a lot of followers, there’s still hope of cracking 2017’s top stories. 29 of the authors had less than 2,000 followers, which you can reach in a matter of months if you manage to write a few popular stories.

The best way to get people to follow you is to remind them to follow you.

If someone reads all the way to the bottom of your article, it’s fair (and well within Medium’s terms of service) to remind them to follow you.

Insight #10: Don’t disable responses.

Only 6 of the top stories had disabled responses.

Imagine someone’s reading your story and thinks of something insightful to add. They scroll to the bottom of your story only to discover that they can’t share their thoughts because you’ve disabled responses.

Are they going to recommend your story? I sure wouldn’t.

Don’t hinder the discourse around your story. Allow your readers to respond to you.

Now let’s get back to writing

A huge thanks to Levent Aşkan, who put in the time compiling these top 252 Medium stories. You can read his story about them here.

Also, thanks to Kande Bonfim for further expanding upon Levent’s dataset.

And if you’re interested in getting more readers in 2016, check out my tips for writing stories on Medium that people will read.

How to write Medium stories people will actually read
_More than 30 million people use Medium each month. They come here in search of something worth reading. Something…_medium.freecodecamp.com

And my unofficial style guide for Medium:

A style guide for writing on Medium
_After spending more than 1,000 hours writing and editing stories for our Medium publication, I’ve decided to create…_medium.freecodecamp.com

Cheers, and happy writing!

I only write about programming and technology. If you follow me on Twitter I won’t waste your time. ?

Headlines

These are the most important part of your story, and you should put some serious thought into them.

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”

Don’t label stories that are part 1 of a series “part 1.” It scares people off, as they will perceive reading it to be a bigger time commitment. And who knows when you’ll get around to writing part 2, anyway.

Also, if your headline is too long, Medium will truncate it. Long headlines can also prevent your top image from appearing in news feeds.

Images

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:

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

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

… 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.

Attribution

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.

In some cases, this might not prove enough for an image right holder. In practice, though, most magazines and movie studios have better things to do than send cease and desist letters to people who merely attributed their copyrighted images.

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.

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

Note that you should not use pull quotes under any other circumstances, as they make the text harder to read. Resist the temptation to use pull quotes to quote your own story, or to tease something you’re about to say anyway. This is self-aggrandizing and wastes your readers’ time.

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. Here’s how you can do this:

How to add code blocks to Medium and use embed tools for syntax highlighting
_Medium has a hidden shortcut that will turn text plain text…_medium.freecodecamp.com

Links

Figure out a way to work a link into a sentence. If a link is vital to a story, put it on its own line and press enter. This will create a preview card, like this:

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

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

Don’t paste URLS directly, like this: http://www.example.com

Do use their top-level domains if it’s a part of their brand, like art.com.

Embedding 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.

Acronyms

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

If an acronym isn’t already widely understood, and you’re going to refer to it more than a few times, you can define it as an acronym 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 acronym 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 acronyms that you don’t need to define: API, AJAX, BIOS, CPU, CSS, HTML, HTTPS, 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.

Text Formatting

You can use bold or italic — never both — to place emphasis on a few words. These slow the reader down, and should be used sparingly. Don’t use bold or italic on links. These already stand out due to the underline.

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

Some old-school-cool print dropcaps

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

Only use one exclamation point, 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, 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 ate 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.

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

Style

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.

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.

Refer to your reader as “you” — not “we” or “us.” “We” are not going to do this tutorial, your reader is going to read your tutorial and do it on their own.

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

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.

When you submit your story to a publication, you should expect for editors to actually edit it. Remember that these people spend a lot more time editing stories than you do, and have a more evolved sense of “what works.” But don’t let this stop you from asking questions and correcting any factual inaccuracies they may introduce.

Be wary of publications that publish your story without making any edits. If they didn’t bother editing it (or even reading it?), they probably won’t put much effort into publicizing it, either.

Oh, and don’t open your story with “This was published on my blog at” or “update: this has been posted on Hacker News.” If you choose to add notes like this, put them at the very bottom of your story. People didn’t click through to your story only to be immediately sent away — they came to read your story.

Note that freeCodeCamp itself is no longer publishes on Medium. Instead we publish here. Here's how to get published in freeCodeCamp's publication.

If you want to learn more about effective writing on Medium itself, read How to write Medium stories people will actually read.

Medium makes it easy to add code blocks and inline

Medium has a hidden shortcut that will turn text plain text…

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

Update October 19, 2016: Medium also now supports the common convention of starting a code block with triple back-ticks. If you type ``` on a new line, Medium will now switch to code input mode. A huge thanks to Luke Esterkyn and the rest of the Medium team for implementing this!

You can also highlight code inline by selecting it, then clicking the backtick key (). For example, you can format text as codefreeCodeCamp()`right in the middle of a sentence.

You can also embed GitHub gists by pasting their URL into a blank line, then pressing enter:

How to Embed web apps

As a bonus, you can 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.

But don’t use images of code.

Even though it may seem convenient to take screenshots of your code and paste them into Medium, don’t do this.

Medium doesn’t yet have an alt-text option, so this will make your code completely inaccessible to developers who are visually impaired. And yes, they are out there.

You also can’t change the font size of a static images, which makes it a pain to read on a mobile phone (which is where most people read Medium).

Finally, this makes it impossible for readers to copy and paste your code.

I know, I know — you shouldn’t copy and paste code anyway.

But let’s face it — people do. And most people will quickly abandon your tutorial if faced with the prospect of manually typing out lots of code.

So to recap:

• use Medium’s native code blocks
• or embed GitHub gists
• use working examples from CodePen and JSFiddle where possible
• but don’t paste images of code

Happy coding and writing about coding!

I only write about programming and technology. If you follow me on Twitter I won’t waste your time. ?

Rich Site Summary (RSS) was developed way back in 1999 as a way to quickly subscribe to blogs and newspapers, back before tools like Twitter feeds made it so easy to find and read articles.

Over the last 17 years, RSS has largely faded from popular usage, but developers never stopped working on it. Today, if you want to streamline your information diet, RSS offers tons of advanced tools that make consuming content a breeze.

You can either actively discover content or passively stumble upon it.

Lets say you decide you want to learn to code. You go to Google and search “learn to code for free.” You find Free Code Camp on the first page of the Google results, sign up, and start progressing through its coding challenges. This is called active discovery.

Now lets say you were just browsing Facebook and you see one of your friends talking about Free Code Camp. This is called passive discovery. You click on the link, bookmark it, then move on with your Facebook-ing, only to never get around to visiting the site again.

My bookmarks. Don’t end up like me.

These examples demonstrate why even if you stumble upon something relevant in social media, you can still end up wasting time. If you don’t have time then and there, you will most likely open a tab or bookmark it. You’ll never get back to, because if you’re busy now, you’re likely to be just as busy later. Contrast this with a google search, which you’ll only do at the exact moment that you need something.

Enter the RSS feed reader

You know how you get a notification when a friend tags on Facebook? Well, you can get the exact same sort of notification from an RSS feed reader when a friend publishes a new article on their blog. Here’s the RSS feed reader Chrome extension that I use on my desktop.

My frequently visited blogs

This will add a nice little icon on your chrome extensions bar, and every time you are on a blog where a feed exists, there will be a little “+” sign so you can “subscribe” to it.

Let’s say you are looking to form better habits, and you find a nice blog about habits like James Clear’s blog. Now, thanks to this Chrome extension, you can just click the + sign and it will add that blog to your feed.

From this point on, whenever James Clear writes an article, you will have a pending notification on that bar until you mark it as read or — better yet — go and read it.

Free Code Camp’s latest articles

Notice how I have subscribed to Free Code Camp’s Medium articles? That’s right — you can even subscribe to your favorite Medium publications, all in one place. This means you won’t have to open Medium and scroll through your its news feed just to find posts from your favorite publications.

Subscribing to blogs in this way saves you massive amounts of time, because you are targeting what you want to read. You can even see the titles, so you never have to open the website only to find out that you’re not interested its newest content.

Using folders and the Dribbble Trick

And that’s not all! You can even make folders, then combine your thematically similar blogs to better manage them. This often helps me when I am trying to focus one particular topic, and looking for inspiration.

Do you use Dribbble for inspiration? Me too! And I follow a lot of designers there. With RSS, you can create folders for Dribbble feeds for individuals designers, so you’ll be the first to know whenever your favorite designers post new content.

People I follow on Dribbble and their new Dribbble shots (the green notifications boxes)

You can do the same for Material UP inspiration.

The Chrome extension comes packed with lots of other useful features, like the ability to star certain blogs combine them, and even subscribe to podcasts.

And if you prefer emails to notifications, you can configure this extension to send you emails about particular blogs, and at designated times of your day when you’re likely free to read them.

You should stop passively surfing.

According to a CNN report, teens spend up to nine hours a day on social media, and check their news feeds up to 100 times a day.

Now, if I didn’t know any better, I would assume that adults are not like teens, and place a higher value on their time. They wouldn’t end spend their days constantly checking social media.

But the reality is, as adults, we end up spending a lot of our time checking our social media instead of actively searching for content that is immediately relevant to us.

When we say we are “surfing the web,” what we are really doing is stumbling upon links which have nice clickbait headlines, only to later realize that the content didn’t teach us anything new. Nor was it relevant to whatever task we were trying to accomplish at the time.

We often find ourselves scrolling through our Facebook news feeds, clicking links our friends have shared, worried that if we don’t do this we may “miss out” on something.

But in all reality, little of this content is essential. Productivity enthusiasts are quick to point out that this “fear of missing out” is misplaced, and that most such content won’t make any real difference in our lives.

The problem with email lists.

The biggest reason for the decline in popularity of the RSS feeds has been that websites have shifted to manually sending you email newsletters with links to their recent blog posts.

It’s nice to stumble upon a website and be able to stay up-to-date by simply giving them an email address. But if they are not the subtle type, and start bombarding me with emails every day, I am going to feel overloaded at first, then eventually unsubscribe.

As you can see, getting 10 promotional emails a day isn’t exactly the most fun way to consume blog content. I have my own designated time to read these posts, and if I don’t get to them because I’m working, I will most likely never get back to them.

With RSS, I have a list of all the blogs that I’ve subscribed to, along with how many new articles each has posted since I last checked them. And I can just leave them as unread for now, then approach them later in a more systematic way.

This way, instead of dealing with random emails that pop up in the middle of my workday, or in the middle of the night when I am trying to sleep, all the content I want to read goes to the same place, and I can get to it at my leisure.

Thanks for reading. I hope this article — and RSS feed readers — can help you be more productive. Again, here’s the free Chrome extension I use for RSS. If you enjoyed this article, make sure to press that green heart to show your support.

Medium’s algorithms put you on a level playing field. Your stories can dominate news feeds. You can crack Medium’s Top Stories list. You can beat out professional writers and celebrities.

I’ll show you how.

But why should you care what some software developer has to say about writing?

A screenshot of my Medium stats page.

Because over the past 30 days, I’ve averaged 12,000 views per day on my Medium stories. Medium’s readers have recommended my stories 13,000 times. And I’m the editor of one of Medium’s largest publications.

In short, I know what writing works here on Medium.

But good writing won’t help you if you can’t get people’s attention.

Weapons of mass attraction

As a writer, you fight a war against indifference. You have to force 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:

Here’s what it looks like on Facebook:

And here’s what it looks like on Twitter:

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.”

Headlines: part art, part science

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

BuzzFeed built a publishing empire on the back of compelling headlines. Here’s a a lexical analysis of 60,000 BuzzFeed headlines, and what works best for them.

I am not saying you should use BuzzFeed-like headlines. But you should be aware of them. They’re filled with hyperbole and fear-of-missing-out. Think about what their effectiveness says about human psychology and the nature news feeds.

Here are some types of headlines that work well on Medium:

• grand pronouncements like “X is over”, “X is broken”, or “X is bull**”
• Headlines that use negative words like “stop”, “never”, and “don’t ever __ again”
• The “I _ and it was _” pattern (for example: “I ate pizza for breakfast and it was glorious”)

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.

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.

A screenshot of the tool’s analysis of this story’s headline. Your mileage my 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.

Arresting Images

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

Medium assigns your opening image the og-image meta property. This means that your opening image will serve as your story’s ambassador everywhere: social media news feeds, Reddit, Google News — even RSS readers.

For this story, I chose an image of Emma Stone portraying an aspiring journalist at her typewriter in the 1960s. It’s from the popular 2011 period movie “The Help.”

A stock photo of someone sitting at their laptop would have looked too generic. Our news feeds are already filled with these pictures.

If you do want to use stock photos, though, there are a ton of free creative commons-licensed stock photos you can use in your stories.

I recommend keeping photos thematically consistent throughout your story. Here’s another image of Emma Stone’s character writing. This helps to break up long stretches of text.

On one story, I used only images from The Dark Knight trilogy:

Salary Negotiation: how not to set a bunch of money on fire
_Pop quiz, hot shot._medium.freecodecamp.com

And I only used images of Peggy Olsen from Mad Men for another:

Getting a raise comes down to one thing: Leverage.
_Maybe you’ve been at your job for a while, and your salary hasn’t kept pace with your city’s cost of living._medium.freecodecamp.com

These stories don’t mention The Dark Knight or Mad Men in their text. The images are there to visually reinforce each story’s message, while lending them flavor.

A spoonful of images helps the text go down.

Another popular technique is to emblazon your story’s headline across your opening image. My friend Kristyna did this on the most-recommended story ever on Medium:

The 37 Best Websites To Learn Something New
_There is absolutely no excuse for you not to master a new skill, expand your knowledge, or eventually boost your career…_entrepreneurs.maqtoob.com

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.

Build momentum with a strong lead

Once your reader clicks through to your story, the trial begins. They are 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 — 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 are 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

Are you writing about health as a non-physician? Are you writing about personal finance as a non-millionaire? You’ll need to overcome any skepticism readers may have about your credibility.

I established my credibility as a writer earlier by posting my recent Medium stats. You’ll need to find an achievement you can trumpet. Something that gives 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. 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.

Speaking of story length…

Medium readers prefer longer stories.

Medium’s data scientists found that 7 minutes is the optimal length for a Medium story.

In practice, a story should be as long as it needs to be, and no longer.

If you can’t come up with at least 5 minutes worth of thoughts, rethink the premise of your story.

One exception to this is stories that are mostly images, embeds, or code.

Write at a sixth-grade level

Just because many of your readers went to college does not mean they enjoy reading at a college level. And many of them will be non-native English speakers.

Paste your story into the Hemingway Editor. This will highlight dense sentences, adverbs, passive voice, and other style issues. It will also assign a grade level to your overall writing.

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.

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 article in their news feed. Tags also make it easier for people to stumble upon your story in search results.

Promote your stories on social media

Once you hit publish, your story will begin to “decay” in Medium’s recommendation engine. As time passes, it will show up in fewer news feeds. The only way to counteract this decay is to get more views and recommends.

The first few hours are critical. Be sure to get a few recommends on your story immediately. These will serve as a proof of concept.

Peer pressure is powerful. Humans are much more likely to click that recommend heart if others humans have already done so.

Share your story on Facebook, Twitter, and LinkedIn. You can view your story’s stats in real time. Ask for feedback from your friends and followers. Incorporate this feedback into your story.

Once people have recommended your story, share it on relevant Reddit subreddits and Facebook groups.

If you have a mailing list, you can blast it out to your subscribers, too.

Submit your story to a large, specialized publication.

Another way to reach a much larger audience is by syndicating your story in one of Medium’s publications. These are communities of writers and editors who specialize in writing about a few key topics, such as health or education.

For example, Free Code Camp’s Medium publication (for which I’m an editor) focuses on development, design, and data science. It has more than 50,000 followers.

When a publication syndicates your story, it will show up in the news feeds of its followers. Publications can also feature your story on their landing pages.

Find out who the editors of these publications are and pitch your story to them.

Ask people to recommend and share.

Medium is still quite new. Most people don’t understand how its recommend and follow mechanisms work.

Here’s my final tip for expanding your readership here on Medium: include instructions and a custom GIF image at the bottom of your stories. This will show people how to recommend your story and follow you.

I only write about programming and technology. If you follow me on Twitter I won’t waste your time. ?

I’ve thought about blogging my coding journey for a while, but nobody would read it unless I pestered them to.

Not me btw.

But if I blog on Medium, Free Code Camp can pick up my blog post and publish it here to the entire community.

Woo hoo!

I’m learning some basic Medium tips, such as:

1) always post with a big image at the top, and use fun images throughout your post.

2) keep your post tightly focused.

3) if you’re struggling with something, other people are probably having that issue too. So blog about it.

Medium makes it so easy to create and share content like this.

I plan to post more often, and hopefully a lot of my posts will end up here in Free Code Camp’s publication.

Check out that snazzy looking publication.

Join me by creating a Medium account, then going to http://medium.freecodecamp.com and clicking the “follow” button.

Then start writing about your coding journey.