Documentation issueshttps://lab.civicrm.org/groups/documentation/-/issues2020-05-16T19:22:16Zhttps://lab.civicrm.org/documentation/docs-publisher/-/issues/96Overhaul the docs &quot;front page&quot;.2020-05-16T19:22:16ZMikeyMJCOOverhaul the docs "front page".Our current list-y approach to the content on docs.civicrm.org works but it's getting less useful as we get more and more docs books. I'd like to open the discussion around what we want from that page and how it should look at the same time as converting it to use the material design aesthetic used in the docs books rather than it's current Bootstrap 3 CSS.
My current thoughts are to switch to presenting the books as "[cards](https://material.io/components/cards)" rather than a list, allowing better control/presentation on Mobile (currently that page is almost unusable on mobile and Google's search console is flagging this as a major issue.
I'm interested in discussion and more ideas - I'm looking to get this done by the second week in May at the latest - I'm planning to prepare some kind of living "demo" in the next day or two!
The most recent preview is here: https://cdn.preview.wales/dp-home/search2/Our current list-y approach to the content on docs.civicrm.org works but it's getting less useful as we get more and more docs books. I'd like to open the discussion around what we want from that page and how it should look at the same time as converting it to use the material design aesthetic used in the docs books rather than it's current Bootstrap 3 CSS.
My current thoughts are to switch to presenting the books as "[cards](https://material.io/components/cards)" rather than a list, allowing better control/presentation on Mobile (currently that page is almost unusable on mobile and Google's search console is flagging this as a major issue.
I'm interested in discussion and more ideas - I'm looking to get this done by the second week in May at the latest - I'm planning to prepare some kind of living "demo" in the next day or two!
The most recent preview is here: https://cdn.preview.wales/dp-home/search2/2020-05-17MikeyMJCOMikeyMJCOhttps://lab.civicrm.org/documentation/meta/-/issues/31Hamburger menu not working on mobile2020-04-20T13:15:49ZDaveDHamburger menu not working on mobilee.g. the user guide. There doesn't seem to be any javascript onClick event attached to it.
I don't remember if it was working before the recent upgrades. But I think so.e.g. the user guide. There doesn't seem to be any javascript onClick event attached to it.
I don't remember if it was working before the recent upgrades. But I think so.https://lab.civicrm.org/documentation/docs-publisher/-/issues/95Implement cookie consent on docs.civicrm.org2020-04-11T14:40:31ZMikeyMJCOImplement cookie consent on docs.civicrm.orgdocs.civicrm.org / docs-publisher will need to handle cookie consent for GDPR/AVR compliance.
The easiest implementation of this is going to be via https://github.com/ConnectHolland/cookie-consent-bundle.docs.civicrm.org / docs-publisher will need to handle cookie consent for GDPR/AVR compliance.
The easiest implementation of this is going to be via https://github.com/ConnectHolland/cookie-consent-bundle.2020-04-30MikeyMJCOMikeyMJCOhttps://lab.civicrm.org/documentation/docs/user-en/-/issues/1Add documentation about partially paid contributions2020-03-16T09:25:19ZBetty DolfingAdd documentation about partially paid contributionsWhen doing PR reviewing we saw that there is no user documentation on partially paid contributions (https://github.com/civicrm/civicrm-core/pull/16546) and how that is handled by CiviCRM. It would be good to add this to the user documentation.When doing PR reviewing we saw that there is no user documentation on partially paid contributions (https://github.com/civicrm/civicrm-core/pull/16546) and how that is handled by CiviCRM. It would be good to add this to the user documentation.https://lab.civicrm.org/documentation/docs/installation-en/-/issues/2Fix google listing2020-03-04T02:22:28ZStoobFix google listingAlthough I don't believe this is an English specific Doc issue I don't know where else to put it.
As of February 9, google "civicrm documentation" and although we are the top listing this **No information is available for this page.** is displayed/
![co](/uploads/84b410fd05c839baa748b7c0ea5f1218/co.png)
Clicking "learn more" in Google brings you to this information page. https://support.google.com/webmasters/answer/7489871?hl=en I don't know why google feels this way. My guess is that it is a meta setting in the Doc website or on the server.Although I don't believe this is an English specific Doc issue I don't know where else to put it.
As of February 9, google "civicrm documentation" and although we are the top listing this **No information is available for this page.** is displayed/
![co](/uploads/84b410fd05c839baa748b7c0ea5f1218/co.png)
Clicking "learn more" in Google brings you to this information page. https://support.google.com/webmasters/answer/7489871?hl=en I don't know why google feels this way. My guess is that it is a meta setting in the Doc website or on the server.https://lab.civicrm.org/documentation/meta/-/issues/30CMS Specific Documentation books2019-11-13T14:20:31ZMikeyMJCOCMS Specific Documentation booksDocumenting CMS specific CiviCRM stuff.Documenting CMS specific CiviCRM stuff.https://lab.civicrm.org/documentation/docs/installation-en/-/issues/1Illustrate clearly the required directory structures for each CMS.2019-10-18T15:07:19ZMikeyMJCOIllustrate clearly the required directory structures for each CMS.To prevent mis-named folders etc we should be clearer what directory structure is expected for each CMS.To prevent mis-named folders etc we should be clearer what directory structure is expected for each CMS.https://lab.civicrm.org/documentation/meta/-/issues/29Licensing documentation - CC-BY-SA-4.0?2019-10-09T10:41:33ZMikeyMJCOLicensing documentation - CC-BY-SA-4.0?We currently license docs content as CC-BY-SA 3.0
We should consider an upgrade from 3.0 to 4.0 this issue will hold discussion and a list potential pitfalls we need to consider when making a decision.We currently license docs content as CC-BY-SA 3.0
We should consider an upgrade from 3.0 to 4.0 this issue will hold discussion and a list potential pitfalls we need to consider when making a decision.https://lab.civicrm.org/documentation/meta/-/issues/28Structure of API Docs with introduction of APIv42019-10-08T13:52:27ZseamusleeStructure of API Docs with introduction of APIv4It was discussed and Tim convinced Mikey that the strucuture should be as follows
- API
-- Introduction
-- Interfaces
-- v3
--- Usage
--- Chaining
--- Joins
...
-- v4
--- Usage
--- Chaining
--- Joins etc
It was discussed to have them merged but the feeling was that the context switching maybe too confusing for developersIt was discussed and Tim convinced Mikey that the strucuture should be as follows
- API
-- Introduction
-- Interfaces
-- v3
--- Usage
--- Chaining
--- Joins
...
-- v4
--- Usage
--- Chaining
--- Joins etc
It was discussed to have them merged but the feeling was that the context switching maybe too confusing for developershttps://lab.civicrm.org/documentation/meta/-/issues/25Make developer docs more accessible to new Civi developers2019-10-07T10:01:05ZgibsonoliverMake developer docs more accessible to new Civi developershttps://lab.civicrm.org/documentation/meta/-/issues/24Improve documentation of APIs2019-10-07T09:38:45ZgibsonoliverImprove documentation of APIshttps://lab.civicrm.org/documentation/meta/-/issues/26Move developer training guide from wiki to docs2019-10-07T10:03:11ZgibsonoliverMove developer training guide from wiki to docshttps://lab.civicrm.org/documentation/meta/-/issues/23Move &quot;core&quot; documentation repositories to GitLab.2020-04-16T15:08:47ZMikeyMJCOMove "core" documentation repositories to GitLab.We're about to deploy "Docs Publisher 1907" which includes, amongst other improvements - the ability to handle automated book publishing from GitLab and GitHub.
Coupled with the planned changes to how we attribute partner contributions (using /spend on GitLab) it would make a lot of sense to move the GitHub based "Core" book repos from GitHub to GitLab (ref: community/community-engagement/wikis/Tracking-Contributions).
The following repos are within the scope of this issue:
1. [ ] [CiviCRM User Guide - English](https://github.com/civicrm/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-en.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
2. [ ] [CiviCRM User Guide - Català](https://github.com/babu-cat/civicrm-user-guide-ca) move to https://lab.civicrm.org/documentation/docs/user-cat.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
3. [ ] [CiviCRM User Guide - Français](https://github.com/civicrm-french/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-fr.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
4. [ ] [CiviCRM User Guide - Español](https://github.com/ixiam/civicrm-user-guide-spanish) move to https://lab.civicrm.org/documentation/docs/user-es.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
5. [ ] [CiviCRM SysAdmin Guide - English](https://github.com/civicrm/civicrm-sysadmin-guide) move to https://lab.civicrm.org/documentation/docs/sysadmin.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
6. [ ] [CiviCRM Developer Guide - English](https://github.com/civicrm/civicrm-dev-docs) move to https://lab.civicrm.org/documentation/docs/developer.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
7. [x] [CiviCRM Training Guide - English](https://github.com/civicrm/civicrm-training-guide) move to https://lab.civicrm.org/documentation/docs/training.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [x] Make GitHub a read-only mirror.
If there's anything which you thing should be a "core book" let us know below - otherwise thoughts gratefully appreciated.
This issue would depend on the completion of #22 to free up the "documentation/docs" namespace for sub-projects.We're about to deploy "Docs Publisher 1907" which includes, amongst other improvements - the ability to handle automated book publishing from GitLab and GitHub.
Coupled with the planned changes to how we attribute partner contributions (using /spend on GitLab) it would make a lot of sense to move the GitHub based "Core" book repos from GitHub to GitLab (ref: community/community-engagement/wikis/Tracking-Contributions).
The following repos are within the scope of this issue:
1. [ ] [CiviCRM User Guide - English](https://github.com/civicrm/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-en.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
2. [ ] [CiviCRM User Guide - Català](https://github.com/babu-cat/civicrm-user-guide-ca) move to https://lab.civicrm.org/documentation/docs/user-cat.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
3. [ ] [CiviCRM User Guide - Français](https://github.com/civicrm-french/civicrm-user-guide) move to https://lab.civicrm.org/documentation/docs/user-fr.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
4. [ ] [CiviCRM User Guide - Español](https://github.com/ixiam/civicrm-user-guide-spanish) move to https://lab.civicrm.org/documentation/docs/user-es.
* [ ] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
5. [ ] [CiviCRM SysAdmin Guide - English](https://github.com/civicrm/civicrm-sysadmin-guide) move to https://lab.civicrm.org/documentation/docs/sysadmin.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
6. [ ] [CiviCRM Developer Guide - English](https://github.com/civicrm/civicrm-dev-docs) move to https://lab.civicrm.org/documentation/docs/developer.
* [x] Create Repo
* [ ] Move Code
* [ ] Update links/references where possible
* [ ] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [ ] Make GitHub a read-only mirror.
7. [x] [CiviCRM Training Guide - English](https://github.com/civicrm/civicrm-training-guide) move to https://lab.civicrm.org/documentation/docs/training.
* [x] Create Repo
* [x] Move Code
* [x] Update links/references where possible
* [x] Update book YAML file in the [Docs Books](https://lab.civicrm.org/documentation/docs-books).
* [x] Make GitHub a read-only mirror.
If there's anything which you thing should be a "core book" let us know below - otherwise thoughts gratefully appreciated.
This issue would depend on the completion of #22 to free up the "documentation/docs" namespace for sub-projects.https://lab.civicrm.org/documentation/meta/-/issues/22Rename this project to &quot;meta&quot; in line with changes to CiviCRM group structures.2019-07-12T10:18:48ZMikeyMJCORename this project to "meta" in line with changes to CiviCRM group structures.I'm proposing that we rename this project from docs to Meta - in line with proposed changes to the structure of groups within CiviCRM.I'm proposing that we rename this project from docs to Meta - in line with proposed changes to the structure of groups within CiviCRM.https://lab.civicrm.org/documentation/meta/-/issues/20Improve meta titles and descriptions2019-07-12T09:52:54Zjoshjosh@civicrm.orgImprove meta titles and descriptions"Docs" are increasingly ranking high on organic search (sample below). This issue is intended to improve the trend by enhance the meta title and descriptions on a per page basis.
- Currently, pages in the user guide display a global meta description "A guide for CiviCRM users". Ideally these descriptions are unique per page.
- Currently the page title appears to be formed by concatentating the 'menu item name' with the site title ("CiviCRM User Guide - CiviCRM Documentation"). This can lead to poor results (like https://docs.civicrm.org/user/en/latest/organising-your-data/overview/ which yields a page title of "Overview - CiviCRM User Guide - CiviCRM Documentation"). Ideally there's more control over the page title, and likely we could remove the "CiviCRM Documentation" portion to better use the avaiable space.
![Sample keyword ranking](/uploads/27edf320878faa4a33e1b3d322f232bb/AwesomeScreenshot-Organic-keywords-for-civicrm-org-2019-07-11-13-07-17.png)"Docs" are increasingly ranking high on organic search (sample below). This issue is intended to improve the trend by enhance the meta title and descriptions on a per page basis.
- Currently, pages in the user guide display a global meta description "A guide for CiviCRM users". Ideally these descriptions are unique per page.
- Currently the page title appears to be formed by concatentating the 'menu item name' with the site title ("CiviCRM User Guide - CiviCRM Documentation"). This can lead to poor results (like https://docs.civicrm.org/user/en/latest/organising-your-data/overview/ which yields a page title of "Overview - CiviCRM User Guide - CiviCRM Documentation"). Ideally there's more control over the page title, and likely we could remove the "CiviCRM Documentation" portion to better use the avaiable space.
![Sample keyword ranking](/uploads/27edf320878faa4a33e1b3d322f232bb/AwesomeScreenshot-Organic-keywords-for-civicrm-org-2019-07-11-13-07-17.png)https://lab.civicrm.org/documentation/docs-publisher/-/issues/86Live site should display specific build errors when manually publishing2018-02-26T03:09:21ZSean Madsensean@leftjoinlabs.comLive site should display specific build errors when manually publishingIf you manually publish a book on the live site, and the publishing system encounters build errors (e.g. due to incorrect syntax in `mkdocs.yml`, currently you'll see a generic error 500 screen. Instead, you should see a screen which displays the specific error, to aid troubleshooting.If you manually publish a book on the live site, and the publishing system encounters build errors (e.g. due to incorrect syntax in `mkdocs.yml`, currently you'll see a generic error 500 screen. Instead, you should see a screen which displays the specific error, to aid troubleshooting.https://lab.civicrm.org/documentation/meta/-/issues/15Explore technologies for automated testing of docs content2017-12-13T23:38:32ZSean Madsensean@leftjoinlabs.comExplore technologies for automated testing of docs contentI think it would be neat to run some automated tests against our docs in some sort of CI setup. Perhaps this is overkill, but I've seen some other docs projects that do this. Look, here's an example of a [pull request I made to docs in a non-CiviCRM project](https://github.com/facelessuser/pymdown-extensions/pull/58) which had a automated spelling test that my PR failed. I thought this was really cool.
Here are some ideas of tests that we could perform:
* Spelling
* [Internal URL standards](https://docs.civicrm.org/dev/en/latest/documentation/markdown/#internal-url-standards)
* Broken links
Need to do more research to figure out how to run these sort of tests without producing false positives (e.g. spelling errors in code snippets, etc). I think it would be neat to run some automated tests against our docs in some sort of CI setup. Perhaps this is overkill, but I've seen some other docs projects that do this. Look, here's an example of a [pull request I made to docs in a non-CiviCRM project](https://github.com/facelessuser/pymdown-extensions/pull/58) which had a automated spelling test that my PR failed. I thought this was really cool.
Here are some ideas of tests that we could perform:
* Spelling
* [Internal URL standards](https://docs.civicrm.org/dev/en/latest/documentation/markdown/#internal-url-standards)
* Broken links
Need to do more research to figure out how to run these sort of tests without producing false positives (e.g. spelling errors in code snippets, etc). https://lab.civicrm.org/documentation/meta/-/issues/14Explore technologies for generating screenshots from machine-readable specs2018-05-26T22:48:15ZSean Madsensean@leftjoinlabs.comExplore technologies for generating screenshots from machine-readable specsReaders love screenshots. Especially in the User Guide, I think they add quite a lot. But they're hard to maintain. A while back I heard somewhere about a tool which would allow documentation writers to specify how a screenshot should be taken in an application. Conceivably, with a tool like this, screenshots would:
* look more consistent
* automatically display the application in the same language as the guide
* be easy to update en masse to follow stylistic application changes (e.g. Shoreditch)
This sounds great, but maybe too good to be true. I can also imagine it being quite hard to use a tool like this. I'm curious though.
I think it could be neat to research this some more and see what tools are out there and how easy it would be for us to adopt them.Readers love screenshots. Especially in the User Guide, I think they add quite a lot. But they're hard to maintain. A while back I heard somewhere about a tool which would allow documentation writers to specify how a screenshot should be taken in an application. Conceivably, with a tool like this, screenshots would:
* look more consistent
* automatically display the application in the same language as the guide
* be easy to update en masse to follow stylistic application changes (e.g. Shoreditch)
This sounds great, but maybe too good to be true. I can also imagine it being quite hard to use a tool like this. I'm curious though.
I think it could be neat to research this some more and see what tools are out there and how easy it would be for us to adopt them.https://lab.civicrm.org/documentation/meta/-/issues/13Explore technologies for improving the workflow of translating documentation2018-12-24T12:01:47ZSean Madsensean@leftjoinlabs.comExplore technologies for improving the workflow of translating documentationOur User Guide is currently [in 4 languages](https://docs.civicrm.org/user/editions). But the non-English versions are significantly out of date. When content updates happen in the English version, it's difficult to propagate those updates to the non-English guides. Likewise, any content updates which happen in non-English guides (though rare) are never captured in other guides.
I had some in-person conversations with people at the UK sprint in October 2017 where we talked about this problem. Here are some actionable ideas we came up with:
* Research other software projects to see how they handle this problem.
* Look for tools (even if in vain) which might be able to extract gettext from Markdown, slice it into translatable chunks, and compile it back into Markdown. (Because if we could do this, then we could use Transifex to translate docs.)
* If we're stuck with our current tooling, consider adopting the following workflow:
1. Choose English as the master language.
1. Only make content updates to the English guide.
1. Propagate content updates to the non-English guides by doing a git merge of the English guide into the non-English guide and using the merge conflicts as indicators for pieces of text that require manual translation. Do this process regularly so that the non-English guides don't fall out of date.Our User Guide is currently [in 4 languages](https://docs.civicrm.org/user/editions). But the non-English versions are significantly out of date. When content updates happen in the English version, it's difficult to propagate those updates to the non-English guides. Likewise, any content updates which happen in non-English guides (though rare) are never captured in other guides.
I had some in-person conversations with people at the UK sprint in October 2017 where we talked about this problem. Here are some actionable ideas we came up with:
* Research other software projects to see how they handle this problem.
* Look for tools (even if in vain) which might be able to extract gettext from Markdown, slice it into translatable chunks, and compile it back into Markdown. (Because if we could do this, then we could use Transifex to translate docs.)
* If we're stuck with our current tooling, consider adopting the following workflow:
1. Choose English as the master language.
1. Only make content updates to the English guide.
1. Propagate content updates to the non-English guides by doing a git merge of the English guide into the non-English guide and using the merge conflicts as indicators for pieces of text that require manual translation. Do this process regularly so that the non-English guides don't fall out of date.https://lab.civicrm.org/documentation/docs-publisher/-/issues/79Allow multiple guides to be published from within one repository2018-11-28T18:34:39ZSean Madsensean@leftjoinlabs.comAllow multiple guides to be published from within one repositoryIn `books/*.yml`, allow a guide to define a subdirectory within the repo that should be used when publishing.
For example, in CiviCRM core, we *might* want to store the Dev Guide, User Guide, and Sysadmin Guide in separate folders within the `docs` directory. This shouldn't be too hard if we just tell `mkdocs` to use a subfolder for its build process.In `books/*.yml`, allow a guide to define a subdirectory within the repo that should be used when publishing.
For example, in CiviCRM core, we *might* want to store the Dev Guide, User Guide, and Sysadmin Guide in separate folders within the `docs` directory. This shouldn't be too hard if we just tell `mkdocs` to use a subfolder for its build process.