Tips and Directions for Community Writers

write-for-dataquest-tips

Thanks for considering submitting to our Community Writers program! This page will provide you with some more details and resources that will help you increase your chances of submitting a successful pitch and ultimately producing a great article.

What We’re Looking for in a Pitch

We want a pitch for a data story article and an accompanying tutorial article that walks readers through how to do some or all of the analysis used in creating the story. Often, for the tutorial, it may be best to focus on a single skill that’s part of the analysis process.

Our goal in publishing both tutorials and data stories is to get as wide an audience for your articles as possible. The tutorials will be useful to anyone who’s learning data science, of course, but the data story should be something that’s timely and interesting even to people who aren’t familiar with the world of data science.

So, for example, you might pitch a data story about how your analysis of newspaper headlines found political bias, and an accompanying tutorial that’s focused on how to do the web scraping required to collect the headlines from your data set. Or, you might pitch a story about a country’s energy usage over time, and an accompanying tutorial about how to do the time series analysis required to follow energy usage patterns over time.

What Are Good Topics for Pitches?

First and foremost, please note that all pitches should be original! If you have posted a project on GitHub, it might still be okay to write about it for us, but if it has been published anywhere else, then we probably won’t be able to accept it.

Any interesting data-driven story could make for a good pitch, but a story that’s related to a predictable upcoming event is always great, as long as we can get the article published before that event.

This could be any sort of event, from a major sporting championship to a regular seasonal weather phenomenon. The idea is that we want to provide interesting data stories relevant to what’s going on in the world. Having that real-world relevance will make more people more likely to tune in, read, and share your story.

This is an example of a data story. This was published just before the 2019 U.S. Open Tournament and Father's Day.

To find predictable upcoming news events, you can Google around for marketing calendars. Here’s one maintained by Twitter. Here’s an independent one that highlights primarily holidays. Not everything on these lists is perfect, and neither list is complete. The more global interest or relevance an event has, the more likely it is to make a good story.

You can also think more broadly about predictable things that happen during the year. What are people likely to be doing a few months from now? What season is it? What will the weather be like? What will be happening in politics? Sports? Culture? What movies are coming out? What hobbies will people be participating in? Think outside the box!

Note that your story doesn’t need to be associated with some timely upcoming event. That can help us to promote it with journalists, but at the end of the day, an interesting story is an interesting story regardless of the time of year. If you’ve found something cool, don’t hesitate to pitch it, even if it doesn’t relate to anything you’re expecting to see in the news!

What Should a Pitch Actually Look Like?

First, pitches should be in English. Sorry, but we can only publish English-language stories for now. Writing samples should also be in English.

Pitches should be a quick, clear summary of what you’re proposing to write about. Try to keep it to no longer than 4 or 5 sentences, using roughly half to describe your data story and why it’s interesting, and the other half to describe your tutorial and what you will cover. Here’s an example of a quick, clear pitch:

I’d like to write a data story analyzing shark attacks by location and comparing them to other local dangers. With beach season coming up, I think this will make an interesting story for swimmers, and help convey that shark attacks are really not a major risk anywhere. The accompanying tutorial will walk readers through how to perform a geographical analysis and how to visualize the results of that analysis using the shark attack data set using Python and Plotly.

Notice that this pitch quickly covers:

  1. What the data story is about
  2. Why this data story is interesting/relevant
  3. What the tutorial will cover
  4. What specific languages/packages the tutorial will use

Your pitch doesn’t need to look exactly like this example, but it should cover those same things.

At the end of our pitch submission process, you’ll be asked the answer to a secret question to prove you’ve read this post. The answer you should put there is Rocket.

What Should an Outline Look Like?

If we like your short pitch, we’ll ask you to provide us with an outline that gives us some more details about the contents of your articles.

The goal here is for use to get a clearer idea of what you’re planning, which will allow us to better assess the pieces, make suggestions, etc.

This is not a formal piece of writing. The best format would be a simple outline using bullet points. Don’t worry about checking spelling or grammar. It probably shouldn’t take more than 1-2 pages of bullet points to outline both articles (remember, the data story article should be short).

When the outline is finished, the easiest way to send it is to simply email a Google document link to the Dataquest email account that replied to your pitch. Make sure that the Google doc’s sharing settings are set to “Anyone with the link can edit” so that we can make suggested edits, add comments, etc.

Tutorial Style Guide

When you’re writing your tutorial, we may give you some instructions specific to your topic. And of course, we’ll help you edit it! But here are a few style rules to keep in mind that will save everyone a lot of time in the editing process:

Use “we,” not “you” or “I”.

We want our tutorials to feel like projects that the writer and the reader are embarking on together — this might seem like a minor thing, but it really makes a big deal in terms of how the tutorial feels.

So instead of something like this:

Next, you need to call the custom function you wrote earlier and pass the arguments I mentioned above...

Tutorials should read like this:

Next, we’ll call the custom function we wrote earlier, and pass the arguments mentioned above...

A good way to check for this is to use Ctrl+F and search for instances of “you,” “your,” “I,” etc. after finishing your draft.

Explain in paragraphs, then demonstrate in code

Generally speaking, whenever we’re telling the reader to write a code snippet, we want to first introduce and explain what the code we’re writing is going to do. We can then include comments in the code that reinforce what we’ve already explained, but coding concepts should never be explained in code comments, and a reader should be able to understand your explanation and code even if they skip reading all the comments. The results produced by running a code snippet can be discussed after the snippet.

Here’s a very simple example of how this might look:

First, we’re going to use a for loop to iterate through our list of lists and append the first item in each row to a new list. To do this, we’ll identify the first item by assigning row[0] to the variable first_item, and then we’ll use the .append() function to add it to new_list.

new_list = [] #create a new listfor row in list_of_lists: # iterate through our list of lists
first_item = row[0] # assign the first item in each row to first_item
newlist.append(first_item) # append each first_item to new_list

If we print this list using print(new_list), we’ll see that…

Note that while the above example has comments for each line, this is not required. Comments are useful to explain the hardest/newest sections in each code snippet, and to reinforce the explanation you’ve offered above of what each code snippet is doing. If something is simple, obvious, or has been explained and used in previous snippets, you probably don’t need to comment it again.

General writing style tips

Keep it simple, short, and clear. The simpler the language you use, and the shorter and clearer your sentences, the easier a time readers will have understanding your tutorial. Avoid using jargon unless it’s required, and keep vocabulary simple. Remember that some of the people reading this tutorial will not be native English speakers. For example, avoid using words like “utilize” — the word “use” is shorter, simpler, will be more widely understood, and means exactly the same thing.

Avoid the passive voice. If you’re not sure about the difference between active and passive voice, here’s a quick reference. It’s best to try to write in the active voice whenever possible, as this leads to more clarity and specificity about precisely what is happening in your code. It also tends to read more smoothly.

Data Story Style Guide

Writing for the data story

Your data story should be short (1,000 words or fewer). Remember that the target audience for this is regular people, not just programmers or data scientists. Remember, also, that the story here is what you found and why it matters, not how you found it. The most important or interesting finding from your analysis should come right at the very beginning.

If this sounds difficult, though, don't worry — we have journalistic experience and we'll be there to help you make your data story great.

Visualizations for the data story

Your data story should definitely include some charts or visualizations. It’s OK to simply provide the default visualizations generated by your code in your first draft — from there, we’ll work with you to produce beautiful charts and visualizations to accompany your story.

What Happens After My Story Is Published?

Once your stories have been published, you’ll submit an invoice for payment. At the same time, we’ll be working to promote your work through our social channels and in our weekly newsletter, which has over, 150,000 subscribers. We’ll also be reaching out to some media contacts to see if there’s media interest in writing about your findings.

After your article has been published on Dataquest, you’ll be free to use it in your portfolio, and you’re welcome to cross-post it on other sites as long as you always include a link back to the original article on Dataquest.