Contribution Workflow

Whether you are writing new content or reviewing existing ones, contributing to The Turing Way generally encompasses the steps discussed in this section. You may refer to the recommendations here to ensure that you have adequately prepared your contribution for review. Please note that the order of these recommendations are not strict and we encourage you to follow the approach that suits you best.

Select a template

Once you have decided on the type of content you want to contribute to The Turing Way, use the relevant template to prepare your contribution.

Note

Please note that we welcome new template contributions. If the chapter or case study templates do not suit your needs, please open a Pull Request with suggestions for improving them. If you want to contribute content for which there is no corresponding template, you are also encouraged to create the missing template and add it to the template collection.

Place new files and folders in appropriate locations

The Turing Way’s Github repository follows an overall file structure where Guides are folders and chapters are sub-folders within them. Similarly, case studies are located inside a case-studies sub-folder within the Guide folders. All folders are located inside the book/website directory.

When writing new content, ensure that the new files and folders you create are placed appropriately to preserve The Turing Way’s file structure.

For example, the Version Control chapter in the Guide for Reproducible Research is placed as follows:

Adding new files and folders

book\website
│
└───reproducible-research <---- (folder for the Guide to Reproducible Research)
│   │   reproducible-research.md <---- (Guide's Landing Page)
│   │   vcs.md <---- (Landing page for the Version Control chapter)
|   |   new-chapter <---- (Landing page for a new chapter)
│   │
│   └───vcs (chapter folder)
│   |   │   vcs-workflow.md
|   |   |   vcs-git.md
|   |   |   vcs-git-commit.md
|   |   |   ...
|   |   |   vcs-personal-stories.md
│   |   │   vcs-checklist.md
│   |   │   vcs-resources.md
│   |
|   |
|   └───new-chapter (new chapter folder)
|   |   |   ...
|    
└───project-design <---- (folder for the Guide for Project Design)
    │   project-design.md
    │   ...

New chapters in the Guide for Reproducible Research should be added like new-chapter in the example above.

Name files/folders appropriately

Please follow The Turing Way’s conventions for naming files. With proper file names, other contributors can easily identify the purpose and location of your files and add to or improve them if necessary.

Follow the style and consistency guidelines

As you write your chapter, keep The Turing Way’s style and consistency recommendations in mind. This ensures that your new content is accessible, and fits the overall style, structure, and formatting of the book.

Add your new files to the book’s table of contents

The book-wide table of contents lives in the _toc.yml file. This file structures The Turing Way and defines the order in which chapters appear. Your chapter’s files should be added to the _toc.yml as appropriate.

For example, because the Statistical Methods Manuscript case study belongs to the Guide for Reproducible Research, it was added to the table of contents as follows:

Updating the book-wide table of contents

- file: reproducible-research/reproducible-research
  sections:
  ...
  - title: Case Studies
    file: reproducible-research/case-studies
    sections:
    - title: A Statistical Methods Manuscript
      file: reproducible-research/case-studies/statistical-methods-manuscript

Reference external sources appropriately

Ensure external sources are properly referenced and included in The Turing Way’s centralised bibtex file as recommended in the style guide

Update the book-wide glossary

The Turing Way maintains a book-wide glossary located in its Afterword. When writing your chapter, update the book-wide glossary with the key terms in your chapter that readers should remember.

Cross check your Pull Request

The content of the templates are only meant to guide and structure your writing. Please remove all of the template’s placeholders, tips, and suggestions from your chapter before you submit your PR for review.