Documentation as code #

This page is for engineers who write documentation with their change, or who maintain the documentation of an extension. In Exponential the documentation lives in the repository, is reviewed in the same pull request as the code, is checked by a command, and is read inside the product. The feature page is The help system.

Contents #

1. Where the documentation lives
2. How it is served
3. Front matter
4. Checking pages
5. Documentation of extensions
6. Writing rules
7. License

Where the documentation lives #

How it is served #

The help system shows every git-tracked Markdown and text file below doc/ in the administration (/exphelp/viewer/<path>), with headings, a table of contents, tables, highlighted code, the navigation of its section and a link to the file on GitHub; a search finds pages by title, headings and text with filters for audience, category and type. Reading the help needs the policy exphelp/read. A file that git does not track is not a page, so a new page appears in the help once it is committed.

Front matter #

Help pages start with a YAML-style block:

Checking pages #

./console exp:help check --below=help/software-engineers/   # links and images of the pages below a path
./console exp:help search "clear cache"                      # what readers will find
./console exp:help show guides/caches.md                     # the metadata and headings of one page
./console exp:help index --rebuild                           # rebuild the index

The check reports errors (a link to a missing file, a link that leaves the installation, an unsafe scheme, a broken image), warnings (an anchor no heading has, an absolute link) and notices (a link to a file that is not a help page). --strict makes warnings fail too. Use relative links only, and link anchors to headings that exist.

Documentation of extensions #

The help shows the documentation every active extension brings (its doc/ directory, README, CHANGELOG, LICENSE) under /exphelp/extensions, in the same viewer and search (Help system for extensions, Documenting your extension). The convention is the same docs as code: README.md and INSTALL.md on top of extension/<name>/, every other page as Markdown (.md) in extension/<name>/doc/, in English (Documenting an extension).

Writing rules #

• Write what exists. Verify every claim in the code, the settings or another page, and say so where the sources do not answer.
• Name the product Exponential. Identifiers such as eZContentObject stay as they are; the old product name appears only as history.
• Real commands only in code blocks; no host names, accounts or passwords of a real installation.
• American English in the interface and the documentation.
• A behavior change gets its upgrade note, a feature its page, a release its changelog (Changelogs and upgrade notes).

Help topics maintained as content in the administration follow their own style guide and review states (Help style guide, Keeping the help up to date).

License #

The documentation is free under the GNU Free Documentation License 1.3; the code is under the GNU GPL, version 2 or later (Free documentation, Documentation and publishing standards).

Related pages #

• The help system
• Help standards
• Contributing upstream
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.