Improving the help
This page is for advocates who find something to improve in the help: a typo, an outdated step, a missing sentence, a
whole missing page. The help pages are the Markdown files in the repository's doc/ folder, so improving them is a
pull request like any other (Develop with Git).
Contents
- The quick way: Edit on GitHub
- The thorough way: a clone
- What helps most
- Writing rules for help pages
- What to avoid
The quick way: Edit on GitHub
- On the help page, press Edit on GitHub. GitHub opens the file.
- Press the pencil to edit. GitHub offers to fork the repository for you.
- Make your change.
- Write a commit message that starts with what it does, for example
Fixed: The layouts help names the Discard button(CONTRIBUTING.md). - Propose the change and open the pull request. Say in one sentence what was wrong and how you checked.
Every pull request is merged; while it is open, its author squashes and rebases it onto main as the reviews ask
(How the project grows).
The thorough way: a clone
For larger changes, work in a clone:
git clone https://github.com/<you>/exponential.git
cd exponential
git switch -c help-fix-layouts
# edit doc/eng-us/help/...
git commit -am "Fixed: The layouts help names the Discard button"
git push -u origin help-fix-layoutsIn an installation, ./console exp:help check reports broken links and images in doc/
(The help system, On the command line). For kernel pull
requests, CONTRIBUTING.md also describes the commit hook and the file manifest (make hooks, make manifest-fix).
What helps most
| Fix | Example |
|---|---|
| A step that no longer matches the screen | A button was renamed |
| A missing step | "First enable the extension" |
| A link to the deeper page | From a help page to the feature page |
| A clearer sentence | Shorter, active, the word on screen |
| A missing page for a common question | You answered it three times in the forums |
| A translation of a page | "A translated page helps every reader of that language" (Free documentation) |
Writing rules for help pages
- Front matter: new pages start with
title,audience,category,order,summary,keywordsandtype, as the existing pages do (The help system, Front matter). - Words on screen: "Use the product name the reader sees on screen", and the button names exactly as shown (help style guide, quoted in Brand and naming rules).
- American English: license, color, behavior.
- Sources: link the page or file that proves a fact.
- Safe Markdown: raw HTML is escaped in the help; use plain Markdown, tables and fenced code (What it shows, and what never).
- License: your change is accepted under the GNU FDL 1.3 or later; say so if any text comes from a source with a different license (Contributing to the documentation).
What to avoid
- Changing many pages in one pull request for unrelated reasons: keep it focused.
- Copying text from websites or books with other licenses.
- Adding personal data, real customer names, keys or server addresses to examples.
- Renaming code identifiers (
eZINI,ezcontentobject) in documentation of code; only the product name changes (Brand and naming rules). - Marketing language in help pages: the help explains; it does not sell.
Related pages
- Advocating for free documentation
- Mentoring a first contribution
- Free documentation
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.