2  Content Guidelines

This chapter coaches you in thinking through what you might say in a post for the rOpenSci website.

2.1 Blog post or tech note?

The rOpenSci blog features two types of posts: long form blog posts for a broad readership, and shorter tech notes aimed at a more technical audience. The word “post” refers generically to either type. 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.

2.2 Themes

Read a few posts and consider what you like (or not) about them. Many 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.

Expand a topic below to see examples.

2.3 Post content

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.

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

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

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

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

2.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, social media, 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.

2.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 share these on social media 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.

2.3.7 Conclusion or summary

Will readers understand your take-home message clearly enough to share on their social media about your post? You might need to remind them of your main points.

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