Documentation styleguide

This page defines the writing standards for the ECA Guide. Following these guidelines helps keep the documentation consistent, clear, and easy to maintain.

This styleguide is based on the GitLab Documentation Style Guide and adapted for the ECA Guide project.

Voice and tone

The ECA Guide aims for a voice that is:

• Concise: Avoid unnecessary words. Get to the point.
• Direct: Use active voice and address the reader directly.
• Precise: Be specific and factual. Avoid vague language.

Write from the reader's perspective. Focus on what the reader can do with ECA, not on what the ECA developers have built.

Active voice

Use active voice instead of passive voice whenever possible. Active voice is easier to read and to translate.

Do:

• ECA executes the action when the event fires.
• Configure the condition to check the user role.

Don't:

• The action is executed by ECA when the event is fired.
• The condition should be configured to check the user role.

Building trust

Do not use marketing language or filler words. Avoid words like "easily", "simply", or "just", as they can be dismissive to readers who find the task difficult.

Do:

• Use this action to send an email when a node is published.

Don't:

• You can easily send an email by simply adding this action.

Self-referential writing

Avoid writing about the page itself. Get straight to the content.

Do:

• ECA supports several event types for content operations.

Don't:

• This page explains the event types that ECA supports.

Language

British English

The ECA Guide is written in British English. Use British spellings such as "colour", "behaviour", "organisation", and "customise".

The only exception is the word modeler, which uses American spelling (single L) to match the Modeler API module name.

Capitalisation

Use sentence case for headings and titles. Capitalise only the first word and proper nouns.

Do:

• ## Configure event conditions
• ## Use the ECA modeler

Don't:

• ## Configure Event Conditions
• ## Use The ECA Modeler

Capitalise names of:

• Drupal module names when used as proper nouns (e.g. ECA, Drupal).
• Third-party products and organisations (e.g. Camunda, BPMN.iO).

Feature names and general concepts should be lowercase (e.g. "events", "conditions", "actions", "tokens").

Contractions

Contractions are acceptable and can make the text feel more approachable. However, avoid contractions:

• When emphasising a negative: use "do not" instead of "don't".
• In error messages or warning text.

Acronyms

Spell out acronyms on first use on a page. For example, write "Business Process Model and Notation (BPMN)" before using "BPMN" alone.

Do not spell out widely known acronyms like URL, HTML, CSS, or API.

Placeholder text

In code blocks, use angle brackets (< and >) to indicate where readers must substitute their own values. For example:

drush eca:execute <event_id>

Outside code blocks, wrap placeholders in backticks as well: <your_site_url>.

Markdown

The ECA Guide is written in Markdown and built with MkDocs using the Material for MkDocs theme. Follow the MkDocs writing guide for general Markdown usage.

Frontmatter

Every page requires YAML frontmatter with at least a title field:

---
title: "Page title"
tags:
  - relevant_tag
---

Headings

• Use a single # heading immediately after the frontmatter, matching the title value.
• Use ATX-style headings (#, ##, ###), not underline style.
• Do not skip heading levels (e.g. do not jump from ## to ####).
• Leave one blank line before and after each heading.
• Do not use links in headings.
• Do not use bold text in headings.
• Avoid heading levels beyond #### where possible.

Paragraphs and line length

• Insert a blank line between paragraphs and between different types of markup (headings, lists, code blocks).
• Keep lines at approximately 80-100 characters where practical to make diffs easier to review.
• Start each new sentence on a new line.

Inline code

Wrap code, file names, directories, configuration values, and similar technical terms in single backticks. For example:

• The eca_base module provides core functionality.
• Navigate to /admin/config/workflow/eca.
• Set the value to true.

Code blocks

Use fenced code blocks with triple backticks. Always specify the language for syntax highlighting. Leave a blank line before and after the code block.

```yaml
id: my_eca_model
label: My ECA Model
```

Common language identifiers: shell, yaml, php, html, json, plaintext.

Links

Internal links

Use absolute paths from the docs/ root directory:

[ECA concepts](/eca/concepts)

When linking to a section index, omit index.md:

• Do: [Concepts](/eca/concepts)
• Don't: [Concepts](/eca/concepts/index.md)

External links

Use standard Markdown link syntax:

[Drupal.org](https://www.drupal.org)

Link text

Use descriptive text for links. Do not use "here" or "this page" as link text.

Do:

• For more information, see event types.

Don't:

• For more information, click here.
• See this page for more information.

Admonitions

Use admonitions to highlight important information. The syntax uses !!! followed by the admonition type, with content indented by four spaces:

!!! note

    This is an important note about ECA configuration.

For collapsible admonitions, use ??? instead of !!!:

??? tip "Click to expand"

    This content is hidden by default.

Supported types include: note, tip, info, warning, danger, example, quote.

For the full list and examples, see the Material for MkDocs admonition reference.

Definition lists

Use definition lists for documenting fields and settings. Format the term in backticks, followed by a line starting with : (colon and three spaces) for the definition:

`Field name`
:   Description of the field. This is the first paragraph.

    This is a subsequent paragraph, indented with four spaces.

Tables

Use tables to present structured data. Keep tables simple and readable:

| Column 1  | Column 2    |
| --------- | ----------- |
| Value A   | Description |
| Value B   | Description |

• Do not leave table cells empty. Use "N/A" or "None" where appropriate.
• Use sentence case for table headers.

Token documentation

Event pages document tokens inside a tip admonition with a Markdown table:

!!! tip "Provided tokens"

    | Token     | Description        |
    | --------- | ------------------ |
    | `[event]` | The event object.  |

Include system

The ECA Guide uses markdown-include for reusable content snippets:

Provides some basic events, conditions and actions, like using the state functionality of Drupal. 
Furthermore, this module contains:

* general conditions for comparison
* setting tokens
* event trigger
* counting list items
* etc.

Include files are located under the include/ directory. Most plugin include files are empty placeholders — add content there to extend auto-generated pages.

Lists

• Use dashes (-) for unordered lists, not asterisks (*).
• Use 1. for every item in ordered lists (the renderer numbers them automatically).
• Leave a blank line before and after a list.
• Make all items in a list parallel in structure.
• Start each item with a capital letter.
• End items with a period only if they are complete sentences.
• Use a colon (:) at the end of the introductory text before a list.

Text formatting

• Use bold for UI element labels (buttons, menu items, page names).
• Use inline code for file names, paths, configuration values, code, and user input.
• Use code blocks for multi-line code, commands, and configuration examples.
• Avoid italics for emphasis. Write clearly enough that emphasis is not needed.

Auto-generated content

The following directories contain auto-generated content and must not be edited manually:

• docs/plugins/ — plugin reference pages
• docs/library/ — library model pages
• toc/plugins.yml — plugin navigation
• toc/library.yml — library navigation

To add supplementary content to plugin pages, edit the corresponding files under include/plugins/ and include/modules/. These are the designated extension points.

Images

Images are stored in docs/images/ and tracked with Git LFS. Use standard Markdown image syntax:

![Alt text describing the image](/images/example.png)

Always provide meaningful alt text for accessibility.

Punctuation

• Use serial (Oxford) commas before the final "and" or "or" in a list of three or more items.
• Use one space between sentences, not two.
• Avoid semicolons; use two sentences instead.
• Avoid em dashes and en dashes; use commas or separate sentences.
• Use straight quotation marks, not typographic ("curly") quotation marks.