Contributing to Documentation

The Cucumber documentation is open source and anyone is welcome to contribute.

Please make ALL contributions to the documentation in docs.cucumber.io.

Process

First-time contributors will have to send a pull request.

Once your first pull request has been accepted, you will be promoted to a committer and gain write access to the GitHub repository. As a committer you should still use pull requests.

Each pull request should only modify/add a single topic. Don’t lump many unrelated document changes into the same pull request.

The title should explain which docs you are modifying/creating (and why). For example [docs] Add tags.md or [docs] Modify tags.md to explain boolean expressions.

The more general contribution process is described in the Cucumber Community Contributing Guide.

Discuss the documentation

It’s great to get feedback on your writing. Start out with small changes, then wait for feedback from other contributors and committers in the pull request.

You can hop into the Cucumber Slack channel #committers-docs or Gitter chat rooms to discuss.

Otherwise - there is always the friendly Cucumber Google group

What to contribute

A great way to start contributing is to answer a mailing list question by improving the docs, and then reply on the mailing list with a link to your contribution.

If you are contributing for the first time we recommend you start by contributing to the Reference documentation. Once you get a hang of that you can start contributing to Learning and Tutorial documentation.

Different styles of documentation

This documentation has three different styles of documentation:

  • Tutorial (step by step guides)
  • Learning (book-style chapters)
  • Reference (the dry, technical style)

In general, it should be brief and to the point.

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away - Antoine de Saint Exupéry

General writing style

  • Every page should start with an informational/motivational paragraph
  • Paragraphs should be short enough to be readable, but long enough to develop an idea.
  • Every page should start with a h1 heading. Sections use h2. Subsections use h3.
  • Break long lines. Insert a new line at around column 80. This is important because review comments can only be added to a line.
  • Write in present tense
  • Use unemotional language, but try to make it a little entertaining (this is hard!)
  • Write in a platform-neutral way as much as possible
    • Cucumber is implemented in several languages, and the docs should not assume a particular platform
    • Some good examples of cross-platform/language docs are Stripe and .NET
  • Use code blocks for all code examples (except Gherkin)
    • If you’re only familiar with one programming language - just add an example for that language - someone else will fill the gaps for the other languages!
    • You can ask for help with the other languages in the help channel for that Slack, or in your GitHub pull request / issue.
  • Use language blocks for text that is only relevant for (a) specific language(s)
    • If you’re only familiar with one programming language - just add text for that language - someone else will fill the gaps for the other languages!
    • You can ask for help with the other languages in the help channel for that Slack, or in your GitHub pull request / issue.
  • All documents should use British English
  • Use links to external sites sparingly
  • Do not use copyrighted material (images, text or other)
  • Illustrations are great, but please use lo-fi drawings. Cucumber’s design team will recreate illustrations according to Cucumber’s brand guidelines.

Tutorial writing style

  • Assume the reader has little or no knowledge of the topic
  • Use a conversational style
  • Don’t go too deep - refer to Learning and Reference docs for depth

Learning writing style

  • Go deeper than tutorials
  • Investigate why and how, pros and cons

Reference writing style

  • Use a h2 section for every major feature.
  • Append (platform-consistent) or (platform-inconsistent) to each header
    • (platform-consistent) means this works the same on all platforms, like Gherkin
    • (platform-inconsistent) means this currently works differently across platforms, like formatter outputs
    • (The Cucumber team is working to make the implementations more consistent, but this takes time)

Toolchain

The documentation is written in Markdown (simple markup).

The documentation is stored in the cucumber/docs.cucumber.io GitHub repository.

Page structure

  • YAML front matter (with title)
  • Introduction paragraph
  • Subtitles

The page’s title from the YAML front-matter is rendered as a <h1> header at the top of the page. Start the body with a paragraph, not a header. If you start with a header, the top of the page will have a h1 followed immediately by another header, which does not look good.

Polyglot pages

Pages can contain variations of the same content that conditionally displays text or source code for a particular programming language.

A language select will be displayed if the page specifies polyglot: true in the front-matter.

The following languages are currently supported:

  • Java
  • JavaScript
  • Ruby

Language-specific source code and paragraphs

Wrap `


You can help us improve this documentation. Edit this page.