Chapter 1 Content Guidelines

1.1 Blog post or tech note?

The rOpenSci blog features two types of posts: long form blog posts for a broad readership, and shorter notes aimed at a more technical audience. We provide details and selected examples of blog posts and tech notes below. Tech notes are written for a narrower audience that wants details. They may include information on a software release with major new features, breaking changes, or significant new documentation. They should provide something a reader could not glean from the documentation itself.

Blog posts are usually published weekly on Tuesdays. Tech notes can be published on any weekday. Both are given the same promotional treatment by rOpenSci.

1.2 Themes of posts

Read a few blog posts and tech notes and consider what you like (or not) about them. Most posts written by community members are about packages that have passed rOpenSci software peer review, however, we have posts on a range of topics and we encourage you to consider these or to propose others.

1.3 What goes in your post?

Since most posts contributed by community members are about packages that have passed software peer review, we use this type of post as an example to outline components you should consider including in your post. Some components would not be included if the post is not about a peer reviewed package.

1.3.1 What message would you like a reader to take away?

What do you feel like you can’t resist sharing with (a very small corner of) the world?

Why did you create the package? Discuss the tools it builds upon or how it works under the hood. You might share your opinions, 5 tips on doing X, what was challenging and how did you meet the challenge, what got you excited or inspired you, something you learned or implemented from the software peer review process, or a compelling real-world example.

Share something a reader could not glean from the package documentation itself.

Use your own voice when you’re writing this. Our website has a professional tone but is less formal than, for example, an academic journal.

1.3.2 Who is your audience?

You can’t write for everyone; you should have an audience in mind. Consider that readers of the rOpenSci blog have a broad range of interests, skills, and experiences. Some will have deep technical knowledge in software development. Some will be domain scientists interested in how to use the package you have developed. Some might be reading as a way to consider how they can contribute to an open source project. Write in a way that any reader can understand what your post is about, but target the majority of its content to a specific audience.

1.3.3 Start with a short summary

Assume no one knows what your package does or why they should care about it. Provide an outline so your reader knows where you’re taking them, especially if your post is long or complex. A good introduction helps potential readers know whether they want to read the rest. Use short headings to guide the reader.

1.3.4 Give a compelling example

  • Explain what you’re going to do in plain language
  • Include some code and a figure or other image
  • Before code snippets, explain what they do
  • After a figure generated by your code, explain what conclusion can be drawn from it. Don’t leave the reader to guess your intent.

1.3.5 Be generous with your appreciation

Did others who are not authors of the post make significant contributions to the package or its inspiration?

Thank reviewers using their first and last names linked to their rOpenSci author page if they have one, or to their relevant online presence (e.g. website, Twitter, GitHub) and link to the software review thread. There is no obligation to do this, but you could note something specific that you improved in your package or in your coding or documentation practice as a direct result of reviewers’ comments.

1.3.6 Consider including a call to action

Do you talk about future plans for package development? Consider opening issues to illustrate your thinking. If you’re willing to consider code or documentation contributions from others, label those issues “help wanted” (no hyphen, no emojis) and “good first issue” or “beginner” if those apply. People who want to contribute to rOpenSci can find these by searching GitHub (example: org:ropensci label:“help wanted” state:open), and we occasionally feature these in our newsletter.

If you want people to tell you how they have used your package, tell them how you want them to do that. Encourage them to submit their use case to our public forum. There’s a template to help. We tweet these to help others see applications and we tag both the package author and use case submitter to give credit. For longer form use cases, they could submit a vignette to include as an article in your package documentation (example).

If you want people to give you general feedback, tell them how you’d like to receive that.

1.3.7 Conclusion or summary

Will readers understand your take-home message clearly enough to tweet about your post? You might need to remind them of your main points.

1.3.8 We love these posts about packages

Now review the technical guidelines for submitting your draft post, and you’re ready to go.