Skip to content
Snippets Groups Projects
Commit 09ae0974 authored by Ron Painter's avatar Ron Painter Committed by GitHub
Browse files

Update index.md changing "book(s)" to "guide(s)"

Changes include "guide book(s)" to "guide(s)" in par. 3 and 4 (lines 8, 10).
parent ef222e3b
No related branches found
No related tags found
No related merge requests found
......@@ -5,21 +5,21 @@ To *read* documentation, go to [docs.civicrm.org](https://docs.civicrm.org) for
This page describes the details of the documentation systems within CiviCRM and how to contribute. We also have a more [basic overview](https://docs.civicrm.org/user/en/latest/the-civicrm-community/contributing-to-this-manual/) on how to contribute to this guide or the user guide.
!!! note "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][migration] is currently underway for this Developer Guide, and a process will [likely](https://github.com/civicrm/civicrm-docs/issues/17) follow for a dedicated Administrator Guide, as well as [extension guides](https://github.com/civicrm/civicrm-docs/issues/14).
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 guides described below, but we are working to eventually consolidate *all* documentation into guides. A [migration process][migration] is currently underway for this Developer Guide, and a process will [likely](https://github.com/civicrm/civicrm-docs/issues/17) follow for a dedicated Administrator Guide, as well as [extension guides](https://github.com/civicrm/civicrm-docs/issues/14).
The rest of **this page describes guide books only** and does *not* cover documentation processes that involve the wiki.
The rest of **this page describes guides only** and does *not* cover documentation processes that involve the wiki.
[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
[wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation
## Guide books in MkDocs
## Guides in MkDocs
We are using [MkDocs](http://www.mkdocs.org) to produce books. The content for each of these books is written in [markdown](/documentation/markdown.md), stored in text files, and hosted in a repository on GitHub. Then, the books are automatically published to [docs.civicrm.org](https://docs.civicrm.org) using our custom [publishing system](https://github.com/civicrm/civicrm-docs).
We are using [MkDocs](http://www.mkdocs.org) to produce guides. The content for each of these guides is written in [markdown](/documentation/markdown.md), stored in text files, and hosted in a repository on GitHub. Then, the guides are automatically published to [docs.civicrm.org](https://docs.civicrm.org) using our custom [publishing system](https://github.com/civicrm/civicrm-docs).
### 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.
In an effort to maintain documentation anchored to specific versions of CiviCRM, some guides store separate versions of the documentation in different *branches* within the repository.
<!-- TODO: clarify "latest" vs "stable" vs "master" -->
......@@ -29,7 +29,7 @@ In rarer cases, if you have an edit that pertains to a specific version, (e.g. d
### Languages
A book can have multiple languages, and we use separate repositories for different languages. For example, you can click *See all X editions* and find the repositories for additional languages.
A guide can have multiple languages, and we use separate repositories for different languages. For example, you can click *See all X editions* and find the repositories for additional languages.
## Contributing to documentation
......@@ -48,7 +48,7 @@ Before diving into editing, you may find helpful information within the followin
### 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 GitHub 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.
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 GitHub guide you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide has its own issue queue. First find the GitHub repository for the guide (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
......@@ -56,9 +56,9 @@ Please see the documentation for editing with Git in the [CiviCRM user guide](ht
### Testing locally with MkDocs {:#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](http://mkdocs.org/), 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.
The most advanced way to work on a guide is to use git to download all the markdown files to your computer, edit them locally, preview the changes with [MkDocs](http://mkdocs.org/), 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. Obtain the source files for the book you want to edit
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)*
1. Fork the repository on GitHub.
1. Clone *your fork* of the repository to your computer
......@@ -68,14 +68,14 @@ The most advanced way to work on a book is to use git to download all the markdo
cd civicrm-dev-docs
```
1. *(optional)* If you have [Docker](https://www.docker.com/) installed, then at this point you can run one of the following commands and then skip to the "view the book" step below.
1. *(optional)* If you have [Docker](https://www.docker.com/) installed, then at this point you can run one of the following commands and then skip to the "view the guide" step below.
1. For folks who have a full Docker for Windows / Mac / Linux environment, run this command:
```
docker run --rm -v "$PWD":/docs -p 8000:8000 -w /docs seanmadsen/civicrm-docker-mkdocs serve --dirtyreload -a 0.0.0.0:8000
```
and skip to the "view the book" step below.
and skip to the "view the guide" step below.
1. For folks who have a legacy or "Home" operating system (Windows 7, 8.1, 10 Home Premium), the situation is a bit more complex. Follow these steps:
1. Check that GitHub folder is in the path: ```c:\Users\<username>\Documents\...```. If it is, all is good; if not, move it there, and edit your GitHub configuration to reflect the changed location.
......@@ -98,7 +98,7 @@ The most advanced way to work on a book is to use git to download all the markdo
sudo pip install mkdocs mkdocs-material pygments pymdown-extensions
```
1. Serve a local copy of the book with MkDocs
1. Serve a local copy of the guide with MkDocs
1. Run:
```bash
......@@ -108,7 +108,7 @@ The most advanced way to work on a book is to use git to download all the markdo
- If you get `[Errno 98] Address already in use` then try using a
different port with `mkdocs serve -a localhost:8001`
1. View the book locally your browser at `http://localhost:8000`.
1. View the guide locally your browser at `http://localhost:8000`.
1. Edit the [markdown](/documentation/markdown.md) with an editor of your choice. As you
save your changes `mkdocs` will automatically reprocess the page and
......@@ -147,13 +147,13 @@ If you'd like to move a page, take the following steps:
1. Run `mkdocs serve` and see if it gives you any warnings about broken hyperlinks. If it does, go fix those.
!!! note
Page redirection *won't work locally* (when previewing with `mkdocs serve`), but it *will* work once the book is published on docs.civicrm.org. The redirection is implemented as part of our [docs-publisher](https://lab.civicrm.org/documentation/docs-publisher) app.
Page redirection *won't work locally* (when previewing with `mkdocs serve`), but it *will* work once the guide is published on docs.civicrm.org. The redirection is implemented as part of our [docs-publisher](https://lab.civicrm.org/documentation/docs-publisher) app.
## Content attribution guidelines {:#attribution}
All CiviCRM documentation content is licensed [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). This means that if you want to copy content out of our docs and use it elsewhere, you're welcome to do so as long as your give attribution to the author.
### How to obtain author information for content within our books {:#attributing-exports}
### How to obtain author information for content within our guides {:#attributing-exports}
This is relevant when you want to copy content *out of* our documentation books.
......@@ -163,9 +163,9 @@ This is relevant when you want to copy content *out of* our documentation books.
### How to displaying attributing for content migrated *into* our books {:#attributing-imports}
The [CiviCRM wiki](https://wiki.civicrm.org/confluence/dashboard.action) and [Stack Exchange](http://civicrm.stackexchange.com/) also use the CC BY-SA 3.0 license, which is convenient because content is regularly migrated into our MkDocs books from these sources. But to comply with the license, we must attribute the original content authors
The [CiviCRM wiki](https://wiki.civicrm.org/confluence/dashboard.action) and [Stack Exchange](http://civicrm.stackexchange.com/) also use the CC BY-SA 3.0 license, which is convenient because content is regularly migrated into our MkDocs guides from these sources. But to comply with the license, we must attribute the original content authors
When migrating content into our docs books which requires attribution, display this attribution at the bottom of the page as follows:
When migrating content into our docs guides which requires attribution, display this attribution at the bottom of the page as follows:
```
## Credits
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment