Commit 96208960 authored by Sean Madsen's avatar Sean Madsen

Add 2017-12-05 meeting notes

parent 08bd87d9
......@@ -8,11 +8,73 @@ These are notes from a meeting of the CiviCRM [Documentation Working Group](http
See our [meeting time pattern](../readme.md#meeting-time)
## Agenda
## Attending
* TBD. See our [unscheduled agenda items](../readme.md#unscheduled-agenda-items).
* Sean Madsen, Seamus Lee, Don Hirst, Eileen (briefly), Michael McAndrew, Michael Devery
## Attending
*
## Should we move docs editing workflow to GitLab?
(conversation, paraphrased)
* Sean: interested in potentially moving docs editing workflow from GitHub to GitLab, so that editing the User/Sysadmin/Dev guides would happen on GitLab. GitHub is working fine for us, but I think that we have some opportunity to help the larger community-wide project of transitioning to GitLab by moving more of our workflow there.
* Seamus: Concerned about adding extra steps for contributors. Most people already have a GitHub account and know how to use it. Editing docs through GitLab would require some additional work for people the first time.
* Sean: agree that getting familiar with GitLab is extra work, but I'm thinking that if we want people to do that work anyway that we can use docs to help nudge them in that direction.
* Michael McAndrew: As a community, are we _really_ moving to GitLab though? Is there a master plan? My understanding is that we're still just evaluating it and not sure whether we're moving to it yet. It would be a shame to move our workflow there and then end up wasting that effort if the community doesn't really get behind GitLab.
* Sean: I noticed that Mathieu started making a [GitLab Roadmap](https://lab.civicrm.org/infrastructure/ops/wikis/gitlab-roadmap) somewhat recently, although it doesn't seem to be finished.
* General sense from that group that it feel like we're in limbo with GitLab.
* People's individual opinions about GitLab:
* Sean: I like GitLab. There are some features that GitLab has that GitHub doesn't.
* Michael McAndrew: Seems like you can do everything with GitLab that you can do with GitHub. On the other hand, everyone is on GitHub, so that's already easy.
* Seamus: haven't done a lot with it. Still trying to get a better understanding of the structure of groups and permissions. But the permissions structure does seem to be more flexible with GitLab than with GitHub. We could potentially use this to our advantage, e.g. allow people to interact more with tickets without needing to grant them merge access to the repo.
* Michael McAndrew: easy to play around with, but harder to get a consensus on how to use it. Needs someone to really spearhead the project of moving more things to GitLab. Feels half-finished. Not really clear how we should be using it.
Group decision:
As a working group we're not clear what the long term direction is for adopting GitLab, so we're not comfortable moving more of our workflow to it. If/when the Core Team can provide more assurance that GitLab is here to stay and that we *should* be using it, then we'll move the docs editing workflow (including issue queues and repos for the three guides) to GitLab.
## What are our overall documentation goals / priorities (1 year / 3?? years)
### Brainstorm
* Reduce issue queues among guides
* Lots of help icons in UI, some of which point to outdated or incorrect URLs. Would be nice to update those.
* Get more extension guides published
* Improve tooling for multi-lingual docs
* This would be mostly User Guide
* Hard keep the translations up-to-date with the latest content updates. We have User Guides in other languages, but they are way out of date.
* Other projects might have better tools for dealing with this. e.g. of Symfony being a project with good multi-lingual docs. Maybe we should research what sort of tools other projects are using.
* There are still so many more English language users than non-English, so we might eventually run into a problem of not having enough translators to help with improving multi-lingual docs.
* Would be interesting to survey the user community to find more users to help with translations.
* Created a ticket for this topic here: https://lab.civicrm.org/documentation/docs/issues/13
* Auto-generated screenshots?
* Sean has heard of some tools (though he can't recall what they were at the moment) which can automate the process of grabbing screenshots from an application. The idea is that instead of putting an image file in the docs, you put machine-readable instructions for producing the image from the application. Then updates to the UI (e.g. Shoreditch) can be automatically propagated to all the screenshots. Likewise, guides in different languages can automatically grab the appropriate screenshots from the localized application so that text in the image matches the language of text in the guide.
* Lots of excitement about this.
* It might be worth researching this more to see how doable it would be.
* Created a ticket for this topic here: https://lab.civicrm.org/documentation/docs/issues/14
* Automated tests for docs. E.g. spell-checking, checks for broken links, etc.
* Created a ticket for this topic here: https://lab.civicrm.org/documentation/docs/issues/15
* Clarifying people who are responsible for certain areas of docs.
### How to do it
* try remote sprint again?
* Yes, people enthusiastic about this.
* How can we improve it?
* Be more diligent about assigning tickets to specific people
* Hold a guided session to teach people to how contribute to docs
* how to incentivize more people to come?
* Not many ideas here
* Might as well give it a try again and see how it goes!
* We should shoot to do one in Feb/Mar
* Make It Happen?
* Sean interested in trying another one of these, potentially with more user-focused docs
* Some support from others about this, but caution that it might not work as well as with Sysadmin because Users will be less likely to donate than system administrators.
## Should we skip the January 2nd meeting?
Yes.
We'll meet next on the first Tuesday in February.
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