Contributor guidelines

Thank you for your interest in contributing to Real World Data Science. This page will walk you through the process of preparing and submitting your idea. If you haven’t done so already, please review our call for contributions before continuing.

Site functionality and ethos

Real World Data Science is built on Quarto, the new open-source publishing system developed by Posit. The site has been designed from the ground up as a platform for data scientists, created by data scientists. Here’s what this means in practice:

  • Contributors can use data science software and tools to create content – e.g. Visual Studio Code, RStudio, Jupyter Lab; Python, R, Observable, and Shiny – allowing for the full integration of text, code, figures, equations, and other elements.

  • Review and editing are transparent and collaborative, again making use of tools data scientists are familiar with – e.g. GitHub, Google Docs – for sharing and revising documents prior to publication.

  • Content can be both engaging and interactive. Many data scientists learn by doing, so code can be made available as R Markdown or Jupyter Notebook files to be reused and experimented with offline. Or, the same documents can be used online through tools like Google Colab and Binder. Where appropriate, the use of interactive displays and Shiny apps is encouraged, allowing for data visualisations to be interrogated and regenerated on the fly.

  • Site users are contributors too. Through annotation and commenting functionality, site users can interact and converse with authors and other members of the Real World Data Science community. And with all source files hosted on GitHub, users of our site can raise issues, or fork and propose improvements – leading to a true exchange of knowledge.

For more on how to work with Real World Data Science via GitHub, check out our repository README.

The submission process

  1. Contact Real World Data Science to discuss your proposed submission.

  2. Write up a short content brief containing the following:

    • Title of submission
    • Author name(s) and affiliation(s)
    • Theme/topic area
    • Target audience
    • Synopsis or sell line, summarising the story and its importance/value (250 words max.)
    • Key audience takeaways
    • Formats and features (e.g., text, audio, video; code blocks, interactive data visualisations, etc.)
    • Accessibility considerations
    • Target length/word count
    • First draft to be submitted by…

    The RWDS_post_template repository on GitHub contains a Quarto document (content-brief.qmd) that can be used to produce a content brief in the style and format of a Real World Data Science article.

  3. Once a content brief is finalised and approved, content is to be prepared in the agreed format and with reference to our style guide. For simple text-based articles, we recommend using Google Docs or Microsoft Word; for submissions that incorporate technical or multimedia content, such as code, equations or interactive graphics, we recommend the Quarto (.qmd) file format. Use the RWDS_post_template repository to create your draft article in Quarto using the correct style and formatting. A sample article in the repo (report.qmd) contains code examples for the Quarto features used by Real World Data Science. Documents can be submitted in Jupyter notebook (.ipynb) and R Markdown (.Rmd) formats but will require conversion before publishing.

  4. Draft submissions should be sent via email to Real World Data Science. Alternatively, contributors can commit their drafts to their own GitHub accounts using the RWDS_post_template repository and the repository link then shared with Real World Data Science.

For more information on how to work with Real World Data Science via GitHub, check out our GitHub repository README.

The review process

Draft submissions will be shared for review with members of the Real World Data Science Editorial Board. Comments and edits to documents will be made via Google Docs/MS Word/GitHub, allowing for (a) version control, (b) open dialogue between reviewers and contributors, and (c) a transparent and well-documented review process.

Once revisions are complete and content is accepted for publication, authors will be provided with HTML files to preview published content. Following sign-off by author and editor, HTML files will be made live.

Post-publication

Contributors and editors will work together to promote content via social media platforms – Twitter/X, LinkedIn, blogs – and in other channels as appropriate – e.g., in response to related questions on Quora or Stack Overflow.

Contributors are encouraged to monitor their content regularly for user comments and discussions. Engaging in discussions with users – whether through the Real World Data Science platform or via social media and other channels – is an effective way of developing an audience: it builds profile for the contributor and their content, and encourages other users to find and interact with content.

Contributors also have the option of uploading the source code and files for their articles to Zenodo, an open science repository, and submitting this material to the Real World Data Science community. When a Zenodo record is created, a DOI is assigned, and this DOI can then be added to your published article on Real World Data Science. For more details on working with Zenodo, see help.zenodo.org.