Meeting - Getting Involved Guide - 27 August 2019 [#3077393]

This meeting is on 27 August 2019 at **16:00 UTC** in the #documentation channel on Drupal Slack. This meeting is text-only, no audio or video, and is asynchronous so everyone can join in as they're available for about 24 hours. After that we'll capture notes from the threads.

Agenda - please feel free to edit this to add items!

Hello and welcome to the Drupal Getting Involved Guide Refresh Meeting!

This meeting:
➤ Usually happens on alternate Tuesdays
➤ is text only!
➤ happens in threads, which you can follow to be notified of new replies even if you don’t comment in the thread. You may also join the meeting later and participate asynchronously!
➤ has a public agenda issue anyone can add to: #3077393: Meeting - Getting Involved Guide - 27 August 2019
➤ :star: Meeting transcripts are still a work in progress, but please comment on the meeting agenda issue so we can grant you credit for attending/contributing!

:zero: *Roll Call!*
Who’s here today? Comment in the thread below if you’d like to introduce yourself and share your first job...

:one: *Meeting Schedule*:

:two: *Issues and progress*: Note the Kanban view at https://contribkanban.com/board/GettingInvolvedGuide

:two: . :one: *Personas*: We have consensus on Personas! #3068287: Consensus on contribution personas

:two: . :two: *Writing Style Toolset*: Loving that we know the styles are already agreed in #3072788: Evaluate, pick, and configure checking/linting tools for the Getting Involved Guide and the toolset is moving along in https://www.drupal.org/project/drupal_org_community/issues/3072788

:two: . :three: *Proposed outline*: The outline needs a review - how do we make it attractive? https://www.drupal.org/node/3071313

:two: . :four: *Community Section*: I have made a community section for us to detail what we are up to and how. What content do we need in here? https://www.drupal.org/node/3074611

:three: *Anything Else?*: What else do we need to talk about?

That’s all for now!

The discussions continue in the threads! Please feel free to chime in within the next 24 hours to be captured in the meeting notes. Thank you very much to everyone for attending, learning, and contributing!

Meeting Transcript

:zero: Roll Call!
Who’s here today? Comment in the thread below if you’d like to introduce yourself
10 replies



Rachel Lawson  1 day ago
Rachel, UK. Trying to catch up after a very full weekend - took goddaughter climbing and camping. Somehow returned her with all her arms and legs

Rachel Lawson  1 day ago
I’m expecting a couple of people missing today, but they will catch up later - advantage of this format!

Tim Lehnen  1 day ago
Will lurk here and catch up later!
Tim, PDX (chinook band lands) - going on vacation to go scuba diving in a couple weeks!
:wave:
1


Aubrey  1 day ago
Aubrey, Boston MA USA (Wampanoag lands). I haven’t participated in any of these meetings before, but I’m interested in learning more!
:wave:
1


Melissa Stamm  1 day ago
Melissa, Nashville TN here.
:wave:
1


Carolyn Shannon (she/her):seedling:  1 day ago
Coming in late from another meeting. Carolyn, Chicago, IL USA suburbs here
:wave:
1


Rachel Lawson  1 day ago
heh - I know that feeling, Carolyn! I was still on a hangout when I posted the first message! :laughing:

amyjune hineline (volkswagenchick she/her):notes:  1 day ago
AmyJune - she/her, coming in a little late. Lots of BADCamp tasks this AM.
Coming atcha from Northern California, Us
:wave:
1


Alona Oneill  1 day ago
Alona. Sorry, I’m little late. Had another meeting.
from Hook42 - San Francisco, CA
:wave:
1


Jordana Fung  1 day ago
Jordana from Suriname. South America . I will be in and out, but feel free to ping me if needed!
:wave:
1

:one: Meeting Schedule: Couple of people missing today but I think we are still doing it right.

3 replies

Rachel Lawson  1 day ago
oh, and I failed to take the transcript last meeting. Huge apologies. The individual issues are up to date. I’ve added reminders to my own calendar so I don’t repeat the mistake. Sorry

Melissa Stamm  1 day ago
So far, so good for me

amyjune hineline (volkswagenchick she/her):notes:  1 day ago
These still work alright for me, they conflict with the camp organizer meetup, but thats so infrequent..

:two: . :one: Personas: We have consensus on Personas! #3068287: Consensus on contribution personas - https://www.drupal.org/project/drupal_org_community/issues/3068287
2 replies

Rachel Lawson  1 day ago
So, we need to store those personas as they are in somewhere we can easily reference. I’ll bring that up in :two: . :four:

Jennifer Hodgdon  16 hours ago
They were already stored. :) See bottom of issue summary. They are at https://www.drupal.org/getting-involved-refresh-personas

:two: . :two: Writing Style Toolset: Loving that we know the styles are already agreed in #3072788: Evaluate, pick, and configure checking/linting tools for the Getting Involved Guide and the toolset is moving along in https://www.drupal.org/project/drupal_org_community/issues/3072788
11 replies

Melissa Stamm  1 day ago
If anyone else wants to evaluate tools,  let me know and I’ll add you to the spreadsheet. But I’m kind of confused on how to proceed from there

Rachel Lawson  1 day ago
I think we need to decide on a way to evaluate them all. What do we want to achieve? Who do we want to be able to use them? If we can answer those questions, we can say what could be a scorecard we can rate them against. Sounds like a little table of questions/answers?

Rachel Lawson  1 day ago
Might be a nice little job, actually

Melissa Stamm  1 day ago
Is the end result a recommendation or a requirement for documentation writers to use the tools we “pick?” Because, honestly, as a content person (not a programmer), I would not use any tool that requires me to do a lot of configuration or command line. Developers might feel differently. I’m just not sure what the goal is. And I just don’t think automated tools will ever take the place of a human editor. At best, I think automated tools are a nice first pass, but human eyeballs and judgment are really important, IMO.
:+1::skin-tone-4:
1


Rachel Lawson  1 day ago
How do you fancy finding some time later in the week to collaborate on a recommendation? Might be easiest way?

amyjune hineline (volkswagenchick she/her):notes:  1 day ago
I have been swamped with BADcamp, but will do some tool testing tomorrow.
:+1:
1


Rachel Lawson  1 day ago
And yeah, it will always be a combination

Rachel Lawson  1 day ago
great!

Rachel Lawson  1 day ago
But also let’s get an agreement on what counts as “good”

Carolyn Shannon (she/her):seedling:  1 day ago
I agree that specific tools may be problematic if they require a lot of config.

Carolyn Shannon (she/her):seedling:  1 day ago
I will do some tool testing as well. I have a couple of ideas…
:+1:
1

Melissa Stamm  1 day ago
If anyone else wants to evaluate tools,  let me know and I’ll add you to the spreadsheet. But I’m kind of confused on how to proceed from there

Rachel Lawson  1 day ago
I think we need to decide on a way to evaluate them all. What do we want to achieve? Who do we want to be able to use them? If we can answer those questions, we can say what could be a scorecard we can rate them against. Sounds like a little table of questions/answers?

Rachel Lawson  1 day ago
Might be a nice little job, actually

Melissa Stamm  1 day ago
Is the end result a recommendation or a requirement for documentation writers to use the tools we “pick?” Because, honestly, as a content person (not a programmer), I would not use any tool that requires me to do a lot of configuration or command line. Developers might feel differently. I’m just not sure what the goal is. And I just don’t think automated tools will ever take the place of a human editor. At best, I think automated tools are a nice first pass, but human eyeballs and judgment are really important, IMO.
:+1::skin-tone-4:
1


Rachel Lawson  1 day ago
How do you fancy finding some time later in the week to collaborate on a recommendation? Might be easiest way?

amyjune hineline (volkswagenchick she/her):notes:  1 day ago
I have been swamped with BADcamp, but will do some tool testing tomorrow.
:+1:
1


Rachel Lawson  1 day ago
And yeah, it will always be a combination

Rachel Lawson  1 day ago
great!

Rachel Lawson  1 day ago
But also let’s get an agreement on what counts as “good”

Carolyn Shannon (she/her):seedling:  1 day ago
I agree that specific tools may be problematic if they require a lot of config.

Carolyn Shannon (she/her):seedling:  1 day ago
I will do some tool testing as well. I have a couple of ideas…
:+1:
1

:two: . :three: Proposed outline: The outline needs a review - how do we make it attractive and welcoming to new potential contributors? https://www.drupal.org/node/3071313
2 replies

Rachel Lawson  1 day ago
I came across https://opensource.guide and wondered if there any parts of the way people are brought into the guide there we can learn from?

opensource.guideopensource.guide
Open Source Guides
Learn how to launch and grow your project.(82 kB)

Carolyn Shannon (she/her):seedling:  1 day ago
I’m sure there are - this particular guide has some good stuff! I also really like the “Learning Paths” on https://lab.github.com/. I wonder if there’s anything we can take from these.

:two: . :four: Community Section: I have made a community section for us to detail what we are up to and how. What content do we need in here? https://www.drupal.org/node/3074611

59 replies

Rachel Lawson  1 day ago
I have added https://www.drupal.org/community/about/getting-involved-guide-refresh and we can add as much content there as we like.

Rachel Lawson  1 day ago
Question: What do we want to take from the completed issues to make into content there as we work on the refresh?
Please just list here and it will keep me busy this week!

Carolyn Shannon (she/her):seedling:  1 day ago
Sorry, I’m not following the question?

Rachel Lawson  1 day ago
For example, we have an issue where we have agreed some personas. I feel we should make a page/doc in that section where we list them (with ref back to the issue)

Melissa Stamm  1 day ago
I think just high level points need to go there. I don’t think all the detail that is captured in tickets needs to be there (but can link to the issue if someone wants to see the details).

Rachel Lawson  1 day ago
no - not the detail - just the high level

Rachel Lawson  1 day ago
Think of it as a guide that says “hey, you want to help make the new guide? This is everything you need to know to participate!” (yes, a bit meta!)

Rachel Lawson  1 day ago
I expect a page detailing how to use the tools

Carolyn Shannon (she/her):seedling:  1 day ago
OK. Will it include templates?

Carolyn Shannon (she/her):seedling:  1 day ago
What other sorts of things are you envisioning? Style guide?

Rachel Lawson  1 day ago
yeah - good idea!

Carolyn Shannon (she/her):seedling:  1 day ago
It would be helpful if there was a basic top-level outline for the guide structure. Scaffolding. If possible.

Melissa Stamm  1 day ago
Oh, I assumed whatever tools/style guidelines would be in the Getting Involved Guide proper. I was seeing this as a description of how we went about this process of updating the guide.

amyjune hineline (volkswagenchick she/her):notes:  1 day ago
A style guide would be a very good idea. Be sure it is accessible from the get-go

Carolyn Shannon (she/her):seedling:  1 day ago
ah

Carolyn Shannon (she/her):seedling:  1 day ago
@Melissa Stamm maybe both?

Rachel Lawson  1 day ago
I imagine there might well be items put here that eventually end up in the guide itself!

Rachel Lawson  1 day ago
(That has only just occurred to me)

Melissa Stamm  1 day ago
In that case, I’d caution against duplicating content. As a content mgr, that’s the bane of my existence (trying to deal with conflicting info on different sites/pages)
:heavy_plus_sign:
3


Rachel Lawson  1 day ago
Heh - too true!

Carolyn Shannon (she/her):seedling:  1 day ago
“How to participate in this project” might include at least a reference to  community “standards” such as the style guide, standards for inclusive language, etc. so we don’t have to re-hash these.

Carolyn Shannon (she/her):seedling:  1 day ago
They can be bullet-point references to other places.

Melissa Stamm  1 day ago
Right, there are already existing pages for style guidelines, so I think linking to those, not rehashing, is the best approach
:heavy_plus_sign:
1


Melissa Stamm  1 day ago
Now whether THOSE style guidelines need any modifications…that’s a whole other can of worms that I’m not sure whether that’s in scope here?? @rachel_norfolk

Carolyn Shannon (she/her):seedling:  1 day ago
“documentation for how we are rebuilding the guide; what our aims are, to which persons we are working, what standards and styles of writing we are implementing”

Carolyn Shannon (she/her):seedling:  1 day ago
So, a “Standards and Styles” page that points to a style guide, language guide, etc.

Rachel Lawson  1 day ago
hmm - good question @Melissa Stamm

Rachel Lawson  1 day ago
we might have “additions”

Melissa Stamm  1 day ago
Yes, pointing to https://www.drupal.org/drupalorg/style-guide/content as a starting point

Carolyn Shannon (she/her):seedling:  1 day ago
yes

Rachel Lawson  1 day ago
like constitutional amendments?

Rachel Lawson  1 day ago
(this is coming from someone who lives in a country without a constitution)
:grin:
1


Melissa Stamm  1 day ago
I know this is open source, community driven, but is there an “owner” of the content style guide? I just ask because it’s already very long and I’d worry about adding more to it

Carolyn Shannon (she/her):seedling:  1 day ago
I think @Melissa Stamm’s point about duplication and authoritative-ness is very well taken here. One of the biggest challenges I see to re-writing the docs at d.o. is duplicate content, content that is tucked away somewhere and we don’t know it exists but this other group uses it authoritatively.

Carolyn Shannon (she/her):seedling:  1 day ago
I know the effort to re-write the guides broke things into “authoritative”/have to request approval for this addition/change and “community documentation”/anyone can participate.

Rachel Lawson  1 day ago
@Melissa Stamm I would say it would be the DA
:heavy_plus_sign:
1


Carolyn Shannon (she/her):seedling:  1 day ago
(To a relative “outsider”, it’s not really clear what the difference is between “authoritative” and “community” documentation.)
:heavy_plus_sign:
2


Carolyn Shannon (she/her):seedling:  1 day ago
It seems as though that confusion, plus a not-intuitive placement for things like glossary, language guide, etc. may be reasons why things end up duplicated. It seems important to use the DA’s official standards/pages here, and point to them consistently.

Melissa Stamm  1 day ago
@rachel_norfolk DA is a big group, is there a committee focused on d.o documentation? (Sorry, I’m still relatively new, just joined the DA, so I’m not entirely clear what it does or how)

Carolyn Shannon (she/her):seedling:  1 day ago
To a relative outsider, I wouldn’t know to look in the drupalorg section of the site for stuff like that.

Carolyn Shannon (she/her):seedling:  1 day ago
As a relative outsider I mean.

Carolyn Shannon (she/her):seedling:  1 day ago
(I’ve been using Drupal and contributing stuff for almost 12 yrs.)

Carolyn Shannon (she/her):seedling:  1 day ago
@Melissa Stamm there is a working group. https://www.drupal.org/governance/doc-working-group

Carolyn Shannon (she/her):seedling:  1 day ago
I didn’t know that until recently.

Melissa Stamm  1 day ago
Oh I heard/saw that there hadn’t been much activity in that group recently. Looks like @eojthebrave is a member and maybe has additional insight

Carolyn Shannon (she/her):seedling:  1 day ago
Yes!

Melissa Stamm  1 day ago
Anyway, for THIS particular issue (https://www.drupal.org/community/about/getting-involved-guide-refresh) I think keeping that page/section as concise and high-level as possible, just outlining the work this group is doing, with relevant links out to style guide and whatever parts of the Getting Involved Guide we may need to point to.

Rachel Lawson  1 day ago
agree

Carolyn Shannon (she/her):seedling:  1 day ago
agree

Rachel Lawson  1 day ago
With regard to the question of who in the DA it falls upon, I think it will either be me or @hestenet (he/him). (I’m inclined to say me - TIm’s more the technical wizardry)

Carolyn Shannon (she/her):seedling:  1 day ago
So the three areas identified, maybe the three pages, are 1) how we are rebuilding the guide/what our aims are, 2) personas, and 3) standards and styles?

Rachel Lawson  1 day ago
yes - sounds like a good plan

Rachel Lawson  1 day ago
I’ll do that this week

Carolyn Shannon (she/her):seedling:  1 day ago
Great! That seems a good orientation.

Melissa Stamm  1 day ago
I think I joined this effort late…was there an initial content audit, user feedback or something that motivated this? (if so, maybe a paragraph on “why” )

Rachel Lawson  1 day ago
https://www.drupal.org/project/drupal_org_community/issues/3077474

Rachel Lawson  1 day ago
that’s what I was thinking as part of 1)

Melissa Stamm  1 day ago
yes, certainly would fit there. I mostly ask because I’m just not clear on how this got started either! :slightly_smiling_face:

Joe  1 day ago
"To a relative “outsider”, it’s not really clear what the difference is between “authoritative” and “community” documentation." ... I think the biggest difference is related to the process required to get changes made. 'Community' documentation is wiki style, you edit it, and your changes are available immediately. There's almost zero oversight/review and it should be treated as such. While "official" docs like the User Guide, and a handful of other one page docs require changes be made via an editorial process that involves review by one or more SMEs. In some ways it mirrors the core vs. contrib system where changes to core go through a know and rigid process while changes to contrib modules are at the discretion of the author.

:three: Anything Else?: What else do we need to talk about?

That’s all for now!
The discussions continue in the threads! Please feel free to chime in within the next 24 hours to be captured in the meeting notes. Thank you very much to everyone for attending, learning, and contributing!

ends.