Contributing to Documentation
The Cucumber documentation is open source and anyone is welcome to contribute.
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
The title should explain what docs you are modifying/creating.
[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.
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
Some reference documentation lives
README files inside standard libraries, such as
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.
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 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
h1heading. Sections use
h2. Subsections use
- 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
- 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
- Contributions in American English is fine - editors will do the translation.
- 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
h2section for every major feature.
(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)