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.
- About a peer-reviewed package developed by the authors
- Major updates to key packages
- Reviewer perspectives
- Contributing to or taking over maintenance of a package
- Summarizing a Community Call
- Describing a creative use case for multiple rOpenSci packages
- Using an rOpenSci resource, such as the Package Development Guide or a task view
- Describe an unsolved problem and a call to action
- rOpenSci Educators Collaborative: What Are The Challenges When Teaching Science With R? (3 posts from unconf18)
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
- rmangal: Making Ecological Networks Easily Accessible talks through the scientific problem and context, shows some code examples, and talks about peer review but doesn’t make that the dominant part of the post.
- Forcing Yourself to Make Your Life Easier is an honest post with some reflection and an important message.
- Relaunching the qualtRics package has an engaging tone while being informative and providing technical details.
- Monkeying around with Code and Paying it Forward gives insight into how the author is thinking about workflows and contributing to rOpenSci
- (tech note) The av Package: Production Quality Video in R is to the point
Now review the technical guidelines for submitting your draft post, and you’re ready to go.