Contributing to Documentation

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

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 of documentation pull requests should be prefixed [docs]. The title should explain what docs you are modifying/creating. 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.

Discussions about docs that are already published can be done in GitBook comments - check the discussion page regularly to see if there are open discussions.

Sometimes it might be quicker to hop into the gitter chat room to discuss in real time, if the people you want to talk to are online.

And finally - there is always the friendly Cucumber Google group

What to contribute

The SUMMARY.md file is the table of contents. As you see, several of the links point to non-existent files. This is what we need help with.

Documentation that isn't reference documentation for a particular library (the majority of the documentation) lives under the /docs directory.

Some reference documentation lives in README files inside standard libraries, such as /cucumber-expressions/README.md and /tag-expressions/README.md.

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.

Toolchain

We use GitBook to write and host the documentation. If you want to contribute you should sign up for a GitBook account and link your GitHub account.

The documentation is written in Markdown (simple markup) and AsciiDoc (richer markup).

The documentation is stored on GitHub

Install the GitBook command-line tool:

npm install gitbook-cli -g

When you have the toolchain installed, you can view the documentation locally:

# Install plugins defined in book.json
gitbook install

# Spin up a local web server serving the docs
gitbook serve

Every time you save an edit to one of the Markdown files, the gitbook server will rebuild the docs.

You may also want to try the GitBook Editor for local editing.

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.aspx)
  • Use codetabs for all code examples (except Gherkin)
    • If you're only familiar with one programming language - just add a single tab - someone else will fill the gaps for the other languages!
  • 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)

results matching ""

    No results matching ""