Commit 10aeb0e5 authored by Sean Madsen's avatar Sean Madsen

Add 2017-11-07 meeting notes

parent 04ccf914
......@@ -8,13 +8,61 @@ These are notes from a meeting of the CiviCRM [Documentation Working Group](http
See our [meeting time pattern](../readme.md#meeting-time)
## Agenda
## Attending
* [Which guides should we store core?](https://lab.civicrm.org/documentation/docs/issues/7)
* Extension README files
* PR review templates?
* Sean Madsen, Jon Goldberg, Michael McAndrew, Neil, Tim Otten, Seamus Lee
## Attending
## Which guides should we store in core?
* Discussion continued from <https://lab.civicrm.org/documentation/docs/issues/7>
* [Emoji poll](https://chat.civicrm.org/civicrm/pl/cjujdw19t7dxxko4hpy3frsy9y) from 2017-10-19:
* 11 people want to continue using separate repos
* 5 people want to store the Dev Guide in the core repo
**Decision**: we will continue using separate repos
## Extension README files
This topic is mostly an informational update
* At the UK sprint last month, Anne Smale and Claire Williams worked on some user-oriented guidelines for improving README files within extensions
* Some discussion here about their work: <https://lab.civicrm.org/extensions/extensions-directory/issues/13>
* Anne agreed to look at the top 20 extensions (going by stats.civicrm.org) and review their README files. Here's one such [pull request](https://github.com/veda-consulting/uk.co.vedaconsulting.mosaico/pull/204) that Anne has made to Mosaico to improve their README.
* Tim (and maybe others?) recently modified `civix` so that it generates a nice-looking README file when running `civix generate:module`
* Here is the [README boilerplate](https://github.com/totten/civix/blob/master/src/CRM/CivixBundle/Resources/views/Code/readme.md.php) used for this generated README file
* For existing extensions that are missing README files, you can run `civix generate:module` from within the module and civix will add the README boilerplate.
* There is also some interest in having a command like `civix generate:docs` which creates a basic MkDocs book for an existing extension. Matt Wire is interested in working on this at some point.
* Some discussion about how extensions README files should be documenting installation instructions.
* Mosaico as example of extension that needs special instructions for installing it
* <https://lab.civicrm.org/extensions/extensions-directory/issues/19>
* There are multiple ways of installing extensions. Not sure how to address this within a boilerplate README section.
* Probably should keep it as simple as possible.
* We should have the installation instructions within the README boilerplate link to the general [extension installation instructions](https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/) in the Sysadmin Guide.
## PR review templates
* Tim has been gathering feedback from the community about the idea of using a template for PR reviews.
* Next step for moving this initiative forward is to figure out how to *distribute* the template (and provide instructions for using it).
* Here are some options
* Use a GitHub "reply template"
* Simple copy-paste from a published location
* A bookmarklet
* Downside to "reply template" is that its stored in each GitHub *users* account (separately) so updating it would be hard
* Sean mentions that we might need to iron out some kinks in the template as we're getting started with using it, so it would be good to choose a distribution strategy in the beginning that allows us to easily update the template.
* Example of a [pull request](https://github.com/civicrm/civicrm-core/pull/11234) where Sean tried using the PR review template.
* **Decisions**
* We will begin by using a simple copy-paste method.
* Will will store the template in the Dev Guide in its own file. We'll link to the raw view of this file on github.com from within the [PR review](https://docs.civicrm.org/dev/en/latest/core/pr-review/) page
* Future updates to this template will happen with the usual PR/discussion process, although we'll seek input from more people for significant changes to the template. Perhaps need to send email to dev list.
*
......@@ -15,7 +15,6 @@
* [Can we find a better web-based UI for simple editing?](https://lab.civicrm.org/documentation/docs-publisher/issues/13)
* Should we retire the docs mailing list (since nobody is using it)?
* What is our plan for the future of the wiki?
* [Which guides should we store core?](https://lab.civicrm.org/documentation/docs/issues/7)
***[:pencil2: Add an agenda item](https://lab.civicrm.org/documentation/docs/edit/master/meetings/readme.md)***
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment