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

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](../
## Agenda
## Attending
* [Which guides should we store core?](
* 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 <>
* [Emoji poll]( 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: <>
* Anne agreed to look at the top 20 extensions (going by and review their README files. Here's one such [pull request]( 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]( 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
* <>
* 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]( 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]( 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 from within the [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?](
* 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?](
***[:pencil2: Add an agenda item](***
Supports Markdown
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