edit

Writing Documentation

To read documentation, go to CiviCRM.org/documentation for the most high-level list of all active documentation.

This page describes the documentation systems within CiviCRM and how to contribute.

Note: the wiki is not covered here

The wiki has historically been CiviCRM's documentation system but is currently being phased out. As of early 2017, documentation is still somewhat split between the wiki the the guide books described below, but we are working to eventually consolidate all documentation into guide books. A migration process is currently underway for this Developer Guide, and a process will likely follow for a dedicated Administrator Guide, as well as extension guides.

The rest of this page describes guide books only and does not cover documentation processes that involve the wiki.

Guide books in MkDocs

We are using MkDocs to produce books, and have the following:

Book English French
User Guide latest,
stable,
4.7, 4.6

repository
latest, stable

repository
Administrator Guide (planned)
Developer Guide latest

repository
Extension Guides (planned)

The content for each of these books is written in markdown, stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to docs.civicrm.org using our custom documentation infrastructure.

Languages

As shown above, a book can have multiple languages, and we use separate repositories for different languages.

Versions

In an effort to maintain documentation anchored to specific versions of CiviCRM, some books store separate versions of the documentation in different branches within the repository.

If you're improving current documentation, please edit the master branch, which will be periodically merged into other branches as needed.

In rarer cases, if you have an edit that pertains to a specific version, (e.g. documentation about a feature in an older version of CiviCRM, which does not require documentation in the latest version), then please edit the branch corresponding to that version.

Contributing to documentation

We welcome contributions, small and large, to documentation!

Resources:

Before diving into editing, you may find helpful information within the following resources:

Submitting issues

The simplest way to help out is to describe a change that you think should be made by writing a new issue in the issue queue for the book you are reading. Then someone will see your issue and act on it, hopefully fast. Each book has its own issue queue. First find the GitHub repository for the book (listed in the above table), then when viewing on GitHub, click on "Issues". You will need an account on GitHub to submit a new issue, but creating one is quick and free.

Editing through GitHub

Suggest specific changes by making the changes within the text editor on GitHub. (You will first need an account on GitHub.)

  1. Find the page in the book you wish to edit.
  2. Click on the pencil icon at the top right.
  3. Make changes within the editor on GitHub.
  4. Click "Propose file change" at the bottom.
  5. Important: Click "Create pull request" and confirm. (You're not done until you create a pull request.)

After you follow the steps above, someone else will review your changes and hopefully accept them, at which point you'll be notified via email.

Editing locally with MkDocs

The most advanced way to work on a book is to use git to download all the markdown files to your computer, edit them locally, preview the changes with MkDocs, then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.

  1. Install pip (python package manager)

    • OS X: brew install python
    • Debian/Ubuntu: sudo apt-get install python-pip python-wheel
  2. Install MkDocs, plus the Material theme and the Pygments syntax highlighter.

    sudo pip install mkdocs mkdocs-material pygments pymdown-extensions
    
  3. Obtain the source files for the book you want to edit

    1. Find the repository on GitHub (see "repository" links above, or the "GitHub" link on the bottom left of screen of the documentation you are reading)
    2. Fork the repository on GitHub.
    3. Clone your fork of the repository to your computer

      git clone https://github.com/YourGitHubUserName/civicrm-dev-docs.git
      cd civicrm-dev-docs
      
  4. Launch a local copy of the book

    1. Run:

      mkdocs serve
      
      • If you get [Errno 98] Address already in use then try using a different port with mkdocs serve -a localhost:8001
    2. View through your browser at http://localhost:8000.

  5. Edit the markdown with an editor of your choice. As you save your changes mkdocs will automatically reprocess the page and refresh your browser.

  6. When you are happy with your edits, use git to commit and push your changes up to your fork. Then submit a pull request on GitHub.

Documenting your extension

TODO