Kedro documentation style guide

This is the style guide we have used to create documentation about Kedro.

When you are writing documentation for your own project, you may find it useful to follow these rules. We also ask anyone kind enough to contribute to the Kedro documentation to follow our preferred style to maintain consistency and simplicity.

We prefer to think of the following list as guidelines rather than rules because have made them lightweight to encourage you to contribute.

Where it's not obvious what the style should be, it's worth consulting the Microsoft style guide. We also use the INCITS Inclusive Terminology Guidelines.

If you are unsure of our preferred style, just do what you can in your documentation contribution, and note any queries. We can always iterate the submission with you when you create a pull request.

Language

• Use UK English

Formatting

• Use Markdown formatting
• Mark code blocks with the appropriate language to enable syntax highlighting
• We use a bash lexer for all codeblocks that represent the terminal, and we don't include the prompt
• We use the format kedro <command> --<flag>=<value1>,<value2> for command examples and suggestions

Links

• Make hyperlink descriptions as descriptive as you can. This is a good description:

• Learn how to update the project pipeline

This is less helpful:

• Learn how to update the project pipeline

Don't write this:

• To learn how to update the project pipeline, see here

Capitalisation

• Only capitalise proper nouns e.g. names of technology products, other tools and services. See the Kedro lexicon section below for additional guidance.
• Don't capitalise cloud, internet, machine learning, advanced analytics etc. as per the Microsoft style guide.
• Follow sentence case, which capitalises only the first word of a title/subtitle. We prefer this "An introduction to pipelines" to this "An Introduction to Pipelines".

Bullets

• Capitalise the first word.
• Don't put a period at the end unless it's a full sentence. Aim for consistency within a block of bullets if you have some bullets with full sentences and others without, you'll need to put a period at the end of each of them. Like in this set.
• Don't use numbered bullets except for a sequence of activities or where you have to refer back to one of them in the text (or a diagram).

Notes

We use .rst directives to bring attention to key points. For example:

Do not pass "Go", do not collect £200.

• You will need to use restructured text formatting within the box. Aim to keep the formatting of the callout text plain, although you can include bold, italic, code and links.

• Keep the amount of text (and the number of callouts used) to a minimum.

• Prefer to use note, warning and important only, rather than a larger range of callout.

  • Use note for notable information
  • Use warning to indicate a potential gotcha
  • Use important when highlighting a key point that cannot be ignored

Kedro lexicon

• Name of our product: Kedro and Kedro-Viz (note capitalisation).
• Use pipeline as this isn't a proper noun. Tend to lower case except if there is a precedent (see next bullet).
• Use Hooks (not hooks, except where it's a necessary part of your code example). We are taking our lead from React here, so capitalising despite it not seeming consistent with other rules.
• Use dataset (not data set, or data-set) for a generic dataset.
• Use data catalog for general discussion about a data catalog but capitalise when you are describing the DataCatalog class or mention specifically the Kedro Data Catalog.

Style

• Keep your sentences short and easy to read.
• Do not plagiarise other authors. Link to their text and credit them.
• Avoid colloquialisms that may not translate to other regions/languages.
• Avoid technical terminology, particularly acronyms, that do not pass the "Google test", which means it is not possible to find their meaning from a simple Google search.
• Use imperatives to make instructions, or second person.
  • For example "Complete the configuration steps" or "You should complete the configuration steps". Don't use the passive "The configuration steps should be completed" (see next bullet).
• Avoid passive tense. What is passive tense? If you can add "by zombies" to the end of any sentence, it is passive.
  • For example: "The configuration steps should be completed." can also be read as: "The configuration should be completed BY ZOMBIES".
  • Instead, you'd write this: "You should complete the configuration steps" or better still, "Complete the configuration steps".

Tone of voice

The Kedro brand has a particular tone of voice: Simple, Friendly and Functional.

Simple

Simple is clear, concise and direct.

We build new skills within your team.

Simple is not vague, verbose or full of jargon.

We leverage your existing organisational resources to synthesise novel competencies.

Friendly

Friendly is approachable and open, and it makes discussions flow.

Kedro: Let’s make change happen. Together.

Friendly is not secretive, negative, vague or non-inclusive.

Kedro is used to cause change in your tier one organisation.

Functional

Functional is compelling, positive, inspiring.

200+ successful projects and counting.

Functional is not try-hard, cliched or hyperbolic.

We’re ultra-sucessful business-builders.