Documentation contribution guidelines

Many thanks for taking an interest in improving the nf-core documentation. To maintain consistency and clarity across the documentation, please follow these guidelines.

1 General writing guidelines

1.1 Use British English

Write in British English, not US English.

  • ✅ “colour” instead of ❌ “color”
  • ✅ “organise” instead of ❌ “organize”

1.2 Use active voice

Active voice makes sentences clearer and more direct.

  • ✅ Active: “nf-core curates pipelines.”
  • ❌ Passive: “Pipelines are curated by nf-core.”

1.3 Avoid gerunds:

Avoid using gerunds (verbs ending in -ing) to make headings and sentences more direct.

  • ✅ “Run pipelines to produce results.”
  • ❌ “Running pipelines produces results.”

1.4 Be direct and brief

Be direct and brief in your instructions and descriptions. Avoid words and qualifiers like may, might, should, could, just, or even.

  • ✅ “To make changes to the pipeline”
  • ❌ “If you would like to make changes to the pipeline”
  • ✅ “Install with Conda”
  • ❌ “You can also install with Conda”

1.5 Avoid Latin abbreviations (e.g., i.e., etc.)

Write out the full phrase instead of using Latin abbreviations.

  • ✅ “For example,” not ❌ “e.g.”
  • ✅ “That is,” not ❌ “i.e.”

1.6 Avoid please and thank you

Maintain a professional and direct tone by avoiding the use of ❌ “please” and ❌ “thank you”.

2 Formatting guidelines

Tip

See Markdown on the nf-core website for instructions on how to use markdown formatting and special elements such as “admonitions” for nice formatting. You’re reading an admonition right now!

2.1 Code and commands

Use inline code formatting for file names or partial commands. Use code blocks for longer code snippets, terminal output, or commands that should easily be copied.

  • ✅ “Use nextflow run nf-core/pipeline_name to execute the pipeline.”
  • ✅ “The pipeline can be executed with the following command:“
  nextflow run nf-core/pipeline_name --input samplesheet.csv

2.2 Headings and titles

Use sentence case for headings and titles. Only the first word and proper nouns should be capitalized.

  • ✅ “Tuning workflow resources”
  • ✅ “Use a specific Nextflow version”

2.3 Lists

  • Use bullet points for lists where the order of items is not important.
  • Use numbered lists for sequential steps.
  • Use numbered headings for guidelines where it is useful to be able to easily refer to a specific section of the docs (like this page!)
  • Use checklists if you’re expecting someone to run through a set of instructions.

Write descriptive link text instead of using URLs directly.

3 Getting help

For further information or help, get in touch on the nf-core #docs channel on Slack.
On this page