Reference tool to help authors to be consistent for writing the tutorials.
Acceptable Post Content
At DataScience+, our goal is to provide high quality tutorials in R that are both unique and compelling. To achieve this, we discourage the submission of low-quality, “me-too” posts. It is the responsibility of the author to conduct some preliminary research prior to writing and submitting a post. In this, the author should ask questions such as:
- The first time I performed this analysis in R, did I struggle with it?
- What other tutorials online cover this topic?
- What aspects of this analysis do other tutorials miss or explain poorly?
- Does my post contribute novel information that others have missed?
- Does my post use a novel dataset, or are these the same data used in other tutorials?
Importantly, any tutorial that you post should be on a challenging subject. If you can easily understand how to conduct the analysis by just reading its help page then it’s probably not an appropriate analysis to do a write-up of here. A good rule of thumb here is to ask yourself, “Did I really struggle with this the first time I did it?” If you did, then others likely had difficulty as well and would probably benefit from a good write-up of what you’ve since learned.
Of course, even if the topic itself is high quality, it’s possible that there’s a better write-up somewhere else online. This is where you need to do your research. We know that you won’t be the first to make a tutorial on the analysis, but we want yours to be the best and to clearly stand out as such. If there are twenty other similar tutorials that all say fundamentally the same thing, it’s much less likely that yours will stand out.
We also want your tutorial to tackle the problem in a novel way. Don’t just use the base datasets package. That’s boring; that’s what everyone else uses; that’s probably not what your readers’ data actually look like. The best tutorials tend to be those inspired by real data that you have actually analyzed in the past. We understand that it’s not always possible to share the actual dataset that you used and we don’t expect you to, but we would always rather see you create a simulated dataset that mimics the original than to cop out and use the datasets package. There’s a much better chance that your readers will benefit seeing the analysis done on data they can relate to than on the
Finally, we ask that you avoid using overly technical language wherever possible, particularly when discussing topics to which readers may have had little exposure. Try to convey the concept using easy-to-understand and relatable examples, anecdotes, and analogies. Many of the concepts that we will write about are highly technical and many readers may not be. To be able to distill these analyses down into easily explained concepts shows a high degree of understanding on the author’s part and makes the post accessible to an even wider audience. Our philosophy here is generally that it’s better for advanced readers to have to skip over an explanation than for beginners to be confused by it.
Writing for a General Audience
In writing for a general audience, it may often be helpful to preface your post with a “Why should I care?” snapshot. Readers might have heard about the concept once or twice before, but not really understand the contexts in which it is important or necessarily why it is important. Because of this, it can help to open with a description of some general situations in which this technique or concept applies, why it matters, and the consequences of ignoring it.
Likewise, you may wish to conclude your post with a discussion of topics and analyses that your tutorial might lead to. Say that you find your data have an unacceptably high kurtosis: what’s the logical next step? We’re not asking you to write that post yourself, but give your readers an idea of where to look to next. Very few analyses live in a vacuum, and most tutorials forget this. We want to guide our readers through the entire analysis pipeline and to give them an appreciation for each step in their analysis, why it is important, and how it informs the larger narrative that they are building with their data.
Both of these points are just suggestions — we leave it to the author to decide when it’s appropriate to take this advice or not.
Headings and Seriation
When using headings in your tutorials, all top-level headings should be enclosed in
<h2></h2> tags. Subheadings should likewise be contained in
<h3></h3> tags. Do not number your headings or subheadings.
All R scripts should be presented in accordance with Google’s R Style Guide. (We know that this style guide is not universally loved, and that’s fine. What we’re emphasizing is consistent presentation of code across many authors for our readers’ ease. If you have any serious objections to anything in Google’s style guide, let us know and we’ll revisit the issue!)
Inline expressions should be contained within
<code>...</code> tags. Displayed code should be placed within
<pre>...</pre> tags. Any R output that you wish to include in your displayed code should be placed within
<em>...</em> tags. For example: <pre>1 + 2<em>3</em></pre>
All code should be fully self-contained and provide a minimum working example that readers can easily re-run in their own R console. You are welcome to provide a link at the end of your post to the full R script used in your tutorial. We suggest that you host it as a GitHub Gist. External data sources should be used sparingly. It is preferred that the provided script contain instructions for generating a sample dataset so that readers can re-run your full analysis on their own.
Fonts and Typesetting Math
For displaying numerical results or data, we do support MathJax typesetting. To use this, enclose inline math expressions in
\(...\). For displayed mathematics, use
\[...\]. Any \(\LaTeX\) math expression can be included within the math delimiters.
For continuity of fonts, please only use the MathJax environment when absolutely necessary. For instance, if you are displaying a complex expression, it is perfectly appropriate. However, if you are simply highlighting some interesting test statistics, please do so within
Let us know if there are any questions!