Commit 321ecfba authored by Sean Madsen's avatar Sean Madsen

Add meeting notes for 2017-10-03

parent d2cf46bf
......@@ -8,11 +8,94 @@ These are notes from a meeting of the CiviCRM [Documentation Working Group](http
See our [meeting time pattern](../readme.md#meeting-time)
## Agenda
* TBD. See our [unscheduled agenda items](../readme.md#unscheduled-agenda-items).
## Attending
*
* Sean, Seamus, Tim
## Topics
### Maintainers for docs repos
* Tim still working on publishing info to codify terminology for repo maintainers, generally. He has been chatting with others at the sprints about this, and is organizing support around some new structures for our workflow, project-wide.
* We'll wait until after Tim has published this info before we try to make agreements about docs repos.
### Storing docs in core
We began discussing the question of whether (and how) to store documentation in the CiviCRM core repository.
Advantages:
* Easier workflow to make one PR that has code changes and docs changes. More atomic.
Disadvantages:
* Tracking docs-only issues becomes somewhat more challenging. Would we use Jira? GitHub? How?
* Giving docs maintainers permissions to merge docs-only changes is more difficult.
Questions:
* Which guides would we want to store in core?
* Not sure about this. Dev Docs seems like the highest priority. But maybe we want to put all three of them in there.
* If we store more than one guide in core, how would the publishing process work?
* Sean: we'd need to change [docs-publisher](https://lab.civicrm.org/documentation/docs-publisher) to be able to publish a guide from within a subdirectory of the repository. This wouldn't be too hard.
* Added https://lab.civicrm.org/documentation/docs-publisher/issues/79 to track this feature.
* What would our workflow be for allowing docs editors (e.g. Sean, Seamus, Michael) to merge docs-only changes?
* We could give these people merge rights but create an understanding that those people should not be merging code changes.
* Or we could follow the Linux model and use forks. In this setup, we'd have a fork of the core repo that docs editors can use at their will to merge docs-only changes.
* How would changes between the two repos be synchronized?
* Probably automatically, with some help from Jenkins. Tim thinks this wouldn't be too hard to setup.
* How would we track the type of issues that we're currently tracking in the docs repos?
* If we used the "Linux model" described above, we could use the GitHub issue tracker within the fork project.
* What about other cases of docs which pertain to code that is *not* in CiviCRM core?
* For example, some of the content in the Sysadmin Guide is actually more relevant to the `civicrm-drupal` repo than it is to `civicrm-core`.
* Can we publish *one* guide from *multiple repositories*?
* Sean: No. This would be hard. Right now we have a one-to-one mapping between repositories and guides. Changing `docs-publisher` to create multiple guides from one repo would be pretty easy. But creating one guide from multiple repos would be harder. We'd need to create some sort of new custom build process for this, and there would be some tricky questions to answer.
* Sean: It'd be great if we could do this though because there are lots of other cases (e.g. civix, buildkit) where the code being documented lives in another repo.
* Tim: This makes me wonder whether it'd be better to just have *all* of CiviCRM's code in one repo.
* (We discussed this a bit but cut the convo sort because it seemed like much too big of a change to consider at the moment)
* What about having separate guides for these separate systems (e.g. a "Civix Guide", and "Buildkit Guide", etc.)?
* Maybe
* Some concern here with having too many guides.
We will move this discussion forward by creating a multi-part emoji poll in Mattermost which allows other people to weigh in on some of the above questions. Sean will set up the poll.
### Other small topics
#### Wiki
We briefly touched on the topic of what to do with the wiki, moving forward
* Seems like everyone in the community is on board with *documentation* moving to MkDocs
* For things like specs, some people still want to use the wiki (and upgrade it), others want to kill the wiki.
* This conversation is difficult because it's also somewhat intertwined with decisions about the future of CiviCRM's usage of Jira, which is an even more difficult and contentious conversation.
* Tim thinks we should try to have some in-person conversations about this at the UK sprint.
#### Universe docs
(paraphrased)
* Seamus: We should get some docs in the Dev Guide which describe the "universe" build that people can create with buildkit
* Sean: Agreed. Here is a ticket for that outstanding work: https://github.com/civicrm/civicrm-dev-docs/issues/195
* Seamus: I might work on this during the sprint
#### Translating the developer guide
(paraphrased)
* Seamus: Do we want to translate the Dev Guide into other languages?
* Sean: We have the User Guide in a couple other languages, but the translation actually isn't complete. It would be best to focus our translation efforts there instead.
* Seamus: I see. Agreed.
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