documentation.md

Writing Documentation

CiviCRM.org/documentation has a nice high-level list of all active documentation.

Wiki migration

As of early 2017, developer documentation on the wiki is under active migration to mkdocs. If you are helping to migrate wiki pages, please read about the migration process to ensure that you understand the workflow including the process of redirecting wiki pages to mkdocs.

Guides in mkdocs

We are using mkdocs to produce guides, and currently have the following two:

• User Guide (repository)
• Developer Guide (repository) (which you are reading now!)

The content for each of these guides is written in markdown, stored in text files, and hosted on GitHub.

How to edit

For minor changes you can simply edit the markdown online using GitHub. However, for a better editing experience we highly recommend installing mkdocs as follows.

1. Obtain the source files for the guide 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 and clone locally.

2. Install mkdocs on your machine.

   1. For Ubuntu

      sudo apt-get install python-pip python-wheel
      sudo pip install mkdocs

   2. For other platforms, follow instructions on mkdocs.org

3. Launch a local copy of the guide

   1. Run:

       cd civicrm-dev-docs
       mkdocs serve

      • If you get [Errno 98] Address already in use then try using a different port with mkdocs serve -a localhost:8001

   2. Go to http://localhost:8000 to view

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

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