Skip to content

Latest commit

 

History

History
65 lines (51 loc) · 2.46 KB

CONTRIBUTING.md

File metadata and controls

65 lines (51 loc) · 2.46 KB
Raw

Style Guide

We love contributions! Here are some tips for creating contributions to this open source course.

General Approaches

Use active voice, i.e. 'you will click..., you learn to create..., etc...' rather than passive voice 'clicking x results in y...'
Start blocks with active VERBS in ALL CAPS, i.e. 'USE..., LEARN...' , rather than 'using x does y' or 'x results in z'.
Use hierarchies and lists to convey structure, i.e...

  • 1 DO something...
    • 1a DO this task to do this thing
    • 1b DO the next task to do this thing
  • 2 DO something else...
    • 2a DO this task to do this thing
    • 2b DO the next task to do this thing
    • 2c DO the next-next task to do this thing
  • 3 DO something else again...
    • 3a DO this task to do this thing
    • 3b DO the next task to do this thing

Sections Headings

The section headings on each page are the same by design, i.e.

  • Why do this
    • Text here...(reasons to use this service for researchers)
  • What is this
    • Text here...(quick service description) ...
  • How to do this
    • Text here...(step-by-step instructions using the GCP console)
  • How to verify you've done it
    • Text here...(what to review to verify that you've been able to use the service )
      ...
  • How to learn more
    • Text here...(links - use icons by content type, shown below)
      1. 📗 READ - one page of this Repo (MD page)
      2. 📺 WATCH - linked YouTube screencasts
      3. 📙 TRY - Jupyter Notebook example
      4. :octocat: TRY - linked GitHub Repos
      5. 📘 EXPAND - linked (external) resources
      6. 🔍 SCAN - search a list in this Repo

Keep Pull Requests small

  • one PR per page of this repo
    • do not combine PRs, i.e. one big PR with updates x multiple pages
    • follow the style and structure of each page - add new or updated info only
  • if correcting typos
    • make that one PR
    • separate it from additions to the text

Content principles

All written content should follow these principles:

  • Approachability: Don't assume reader has prior knowledge, spell out all acronyms
  • Brevity: Keep it simple, link to outside content for deeper dives
  • Curation: Amplify community best practices vs. any individual's point of view

Content should maintain a quickly scanable tone. This course is meant as an introduction to using GCP services for those who are new to cloud and working in bioinformatics research.