Meeting - Contribute to Documentation - 1 December 2020

This meeting is on 1 December 2020 at 17:00 UTC** (9 AM US/Pacific, 12 noon US/Eastern, 8PM in Paris) 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 Contribute to Documentation meeting!

This meeting:
➤ Usually happens on the first Tuesday of the month at 17:00 UTC
➤ 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.

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 tell us why you came to the meeting today.

:one: Contributor Guide content updates
- We have a Google spreadsheet for the content migrations in the old Getting Involved Guide:
https://docs.google.com/spreadsheets/d/15bLdzwwe9xECfTGM4miAQRzUs3pGqz3z...
Only a few items left -- mostly Contributor Tasks from https://www.drupal.org/contributor-tasks -- jhodgdon is coordinating migrating those.
- We also have several Contribution Areas that need updates and new content. Parent issue: https://www.drupal.org/project/drupal_org_community/issues/3137918
- Recent progress:
-- MargyLY and AmyJune have been working on a guide to planning DrupalCamp events. Issue: https://www.drupal.org/project/event_organizers/issues/3165327

:two: Graphics for the Community and Contributor Guide areas
https://www.drupal.org/project/drupal_org_community/issues/3184840

:three: Names of the "Official" and "Community" documentation areas
https://www.drupal.org/project/drupalorg/issues/3176075

:four: (your agenda item here!)

:five: (your agenda item here!)

:six: *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 log

jhodgdon (she/her) Dec 1st at 9:05 AM
:one: Contributor Guide content updates




78 replies

jhodgdon (she/her)  2 days ago
We have a Google spreadsheet for the content migrations in the old Getting Involved Guide:
https://docs.google.com/spreadsheets/d/15bLdzwwe9xECfTGM4miAQRzUs3pGqz3zUXJmQi_CbEI/edit?usp=sharing
Only a few items left -- mostly Contributor Tasks from https://www.drupal.org/contributor-tasks  -- jhodgdon is coordinating migrating those.

Drupal.org
Contributor Tasks
Note: This section is in process of being migrated to the Find a task page in the new Contributor Guide. Try searching there for a task instead of looking in this section -- some tasks have been moved there already. When the migration is complete, we will remove this section.
Feb 1st, 2012

jhodgdon (she/her)  2 days ago
We also have several Contribution Areas that need updates and new content.  Parent issue: https://www.drupal.org/project/drupal_org_community/issues/3137918

Drupal.org
[Meta] Create content for Contributor Area sections
We need to create content for all of the Contribution Areas. Here are the guidelines for how/when/why to create a contribution area page: Guidelines for contribution areas. For each Contribution Area page, we need to create a child issue with the following summary: Develop/edit content for Contribute to WHATEVER IT IS Area Page of the Contributor Guide.
May 19th

jhodgdon (she/her)  2 days ago
Recent progress:  @MargyLY  and @AmyJune (volkswagenchick she/her) and I have been working on a guide to planning DrupalCamp events. Issue: https://www.drupal.org/project/event_organizers/issues/3165327

Drupal.org
Event planning documentation
Documentation location/URL This issue is about these pages in the Contributor Guide on the subject of event planning: Area: https://www.drupal.org/community/contributor-guide/contribution-areas/event-planning Skill: https://www.drupal.org/community/contributor-guide/skill/event-planning Reference info section: https://www.drupal.org/community/contributor-guide/reference-information/event-plan Guidelines for the content types in the new Contributor Guide:
Aug 14th

rachel_norfolk  2 days ago
Lots done so far!

Carolyn Shannon  2 days ago
Nice! Way to go.

AmyJune (volkswagenchick she/her)  2 days ago
I am helping with a Pantheon contribution event through December.. I will be doing a mini workshop on documentation in two weeks and hopefully get some new folks excited.
:banana-dance:
1


jhodgdon (she/her)  2 days ago
Sounds great!

jhodgdon (she/her)  2 days ago
It would be good to get more of the Contributor Tasks migrated to the new Guide. I'm a bit overwhelmed because in many cases, I'm not sure if "we're still doing things that way" or even if "it's still something we want contributors to do", looking at the old list of tasks.
:heavy_plus_sign:
1


Carolyn Shannon  2 days ago
Helping out w/this - will be working w/@AmyJune (volkswagenchick she/her) and @sparklingrobots (DMs open) on augmenting Pantheon’s docs to make it easier for folks to contribute to Drupal.
:partyparrot:
1


rachel_norfolk  2 days ago
I’m wondering about the event planning guide and whether quite a few of the “background” pages are actually tasks?

Carolyn Shannon  2 days ago
@jhodgdon (she/her) is that where I can be most helpful (getting Contributor tasks migrated)?

Carolyn Shannon  2 days ago
Or are these decisions that need to be made before migratin’ can be done?

jhodgdon (she/her)  2 days ago
Regarding the Event Planning guide, I would like to have the Tasks mostly be stand-alone, something a contributor can browse through and do on the spot. Event planning... doesn't really fall into that?

jhodgdon (she/her)  2 days ago
I mean you can't just "contact sponsors for an event" out of the blue.

jhodgdon (she/her)  2 days ago
Regarding migrating the existing tasks, yes some decisions need to be made. What I've been doing (I've tried it once or twice anyway!) is posting a thread in #mentoring and cc #documentation and #contribute , asking for input on a particular task... let me find one of the ones I've posted before.
:ok:
1


jhodgdon (she/her)  2 days ago
https://drupal.slack.com/archives/C4K9UPX9P/p1605902907235200

jhodgdon (she/her)
Contributor Task Migration of the Day: https://www.drupal.org/contributor-tasks/write-tests -- This task writeup is very outdated, as it's using SimpleTest and not PHPUnit. I'm wondering if we even want/need a dedicated task for that vs. writing a patch in general... I do see that it's linked from the Remaining Tasks template https://www.drupal.org/docs/develop/issues/fields-and-other-parts-of-an-issue/special-issue-summary-templates/issue-1 so maybe we do need to have a task writeup... ??? I'll cross-post this in #contribute too.
Posted in #mentoring | Nov 20th | View message

jhodgdon (she/her)  2 days ago
So @Carolyn Shannon you could do the same -- adopt a particular Task that needs migrating, solicit input, and migrate it. They usually need a lot of editing, like pointing to the current docs links not outdated links, and IRC -> Slack, etc.
:+1::skin-tone-4:
1


rachel_norfolk  2 days ago
To be honest - I’d rather see anything that can be described as a series of steps as a task. Obviopusly, not every task can be executed without “authority”

jhodgdon (she/her)  2 days ago
That is OK too.

Carolyn Shannon  2 days ago
OK

jhodgdon (she/her)  2 days ago
My concern is someone goes to "Find a task" and sees things that are just not really doable.

rachel_norfolk  2 days ago
I think, then, we need to find the right words to say that other tasks or reading is needed before this task can be started (edited) 

Carolyn Shannon  2 days ago
Before You Begin

jhodgdon (she/her)  2 days ago
Or that "This task is only useful if you are involved in planning a DrupalCamp"

rachel_norfolk  2 days ago
Yes!

jhodgdon (she/her)  2 days ago
We do have prerequisite knowledge field already.

jhodgdon (she/her)  2 days ago
But this is kind of "prerequisite situation"

rachel_norfolk  2 days ago
And it should reference the role of conference organiser, anyway

jhodgdon (she/her)  2 days ago
Actually we have "Background knowledge" field already.

rachel_norfolk  2 days ago
so, a conference organiser might do task 1 2 and 3

jhodgdon (she/her)  2 days ago
Yeah, good point.

jhodgdon (she/her)  2 days ago
But.

rachel_norfolk  2 days ago
And the Event planning background should list the roles expected and then the tasks come from that
:heavy_plus_sign:
1


jhodgdon (she/her)  2 days ago
So here's the other side of it.

jhodgdon (she/her)  2 days ago
Someone comes to Contributor Guide, and they say, oh, I have an hour, I need something to do, so the guide page says go to https://www.drupal.org/community/contributor-guide/find-a-task

Drupal.org
Find a task
This guide is always evolving. If you'd like to help improve it, the best starting point is the Contribute to the Contributor Guide page. In particular, the task list here is incomplete -- additional tasks are being migrated to this section from the previous contributor task list.
Feb 11th (39 kB)

jhodgdon (she/her)  2 days ago
They browse there for tasks.

jhodgdon (she/her)  2 days ago
They find something like "Solicit sponsors for a DrupalCamp". That is not something they can do today.

rachel_norfolk  2 days ago
doesn’t have to be

Carolyn Shannon  2 days ago
Right. There are prerequisites

rachel_norfolk  2 days ago
That’s okay

jhodgdon (she/her)  2 days ago
OK

Carolyn Shannon  2 days ago
The camp has to be in a place that’s ready for sponsors to be solicited.

jhodgdon (she/her)  2 days ago
Right, but does someone looking for a task to do today want to see those tasks listed on the page?

jhodgdon (she/her)  2 days ago
The tasks that are there now are all things that you can just pick up and do.

rachel_norfolk  2 days ago
Are we saying we need a clever way to achieve that “what can I do today, with skills but nothing else?“? (edited) 

jhodgdon (she/her)  2 days ago
yes

Carolyn Shannon  2 days ago
good question. If it’s not an “active” task (can’t do it right now, but maybe could sign up to do it for a camp in the future)

rachel_norfolk  2 days ago
In that case, that’s an issue we need to work on

jhodgdon (she/her)  2 days ago
So maybe we need a field (checkbox) on the tasks saying "Is this a stand-alone task"?

rachel_norfolk  2 days ago
yeah - that’s what we need!

rachel_norfolk  2 days ago
:wink:

jhodgdon (she/her)  2 days ago
If we have that, we can have a filter on "Find a task" that filters for stand-alone

rachel_norfolk  2 days ago
I like it

Carolyn Shannon  2 days ago
sounds good - as long as we make it clear to the person checking the box what it will do.

jhodgdon (she/her)  2 days ago
and then we can feel free to add the non-stand-alone tasks and not degrade the experience of contributors lookgin for things to do.

rachel_norfolk  2 days ago
yeah - true

jhodgdon (she/her)  2 days ago
OK I'll make an issue for adding that to the Task content type.

jhodgdon (she/her)  2 days ago
after the meeting.

Carolyn Shannon  2 days ago
good idea

rachel_norfolk  2 days ago
I’m really keen we have as much as possible as tasks and roles attached to them

jhodgdon (she/her)  2 days ago
Thanks! This was an excellent discussion.
:partyparrot:
1


jhodgdon (she/her)  2 days ago
I think you are right @rachel_norfolk

rachel_norfolk  2 days ago
It happens on occasion
:tada:
1


jhodgdon (she/her)  2 days ago
@Carolyn Shannon do you feel empowered to work on the migrations, soliciting feedback if you're not sure they are current/useful tasks?

Carolyn Shannon  2 days ago
Yes. Sounds like a good place to start.

jhodgdon (she/her)  2 days ago
Great! Thanks! I will be busy for a while so having someone else work on the migrations will be wonderful!

jhodgdon (she/her)  2 days ago
I think targeting one at a time for feedback is good, gives people something to focus on.
:heavy_plus_sign:
2


Carolyn Shannon  2 days ago
OK, sounds good.

AmyJune (volkswagenchick she/her)  2 days ago
That approached well for the work @MargyLY

jhodgdon (she/her)  2 days ago
Here's the issue for "stand-alone": https://www.drupal.org/project/drupalorg/issues/3185876

Drupal.org
Add field to Contributor Tasks for "Stand-alone"
Problem/Motivation When you go to https://www.drupal.org/community/contributor-guide/find-a-task as a contributor, you want to find a task you can do today.
Dec 1st

Carolyn Shannon  1 day ago
I’m stuck on remembering how to migrate a contributor task. I went to the spreadsheet and found one that needs to be moved (Create a patch for a Drupal core issue). I know I need to create a new task so it will appear in the “Find a task” list. Where I’m stuck:
I don’t remember how to create a new task, where that link lives.  Can you help?
Notes field in spreadsheet asks “Should be reformulated so it talks about merge requests and patches both?” - would we duplicate info from “Creating issue forks and merge requests” in the Git for Drupal project maintainers doc, or just point at that? And given that this is the new workflow, do we still want to provide instructions on rolling patches? Or is this one of the things I should ask the core community about?
 (edited) 
Drupal.org
Creating issue forks and merge requests
Video A video introduction to this workflow can be found at https://youtu.be/NIWCXE-aM6Y
Sep 23rd

jhodgdon (she/her)  1 day ago
Great qustions!

jhodgdon (she/her)  1 day ago
The links to create new Contributor Guide items live on the page that talks about the guidelines for the content types, which is: https://www.drupal.org/community/contributor-guide/reference-information/guidelines-contributor-guide/content-types

Drupal.org
Contributor Guide content types
Most of the content in the Guide is divided up into 5 types: Contributor Skill, Contributor Task, Contributor Role, Contribution Area, and Contributor Reference Information. So, if you have content to add, ask yourself these questions to figure out which content type to use:
Feb 27th

jhodgdon (she/her)  1 day ago
My advice is to never duplicate information between two pages on drupal.org of whatever type, but always to link.

jhodgdon (she/her)  1 day ago
If we have the same information in two places, eventually they will diverge and it's a maintenance nightmare.
:heavy_plus_sign:
1


jhodgdon (she/her)  1 day ago
Also, linking to the docs, especially in that case, will also get them to know there's that whole section about Git docs (there may be other things in there that are useful).

jhodgdon (she/her)  1 day ago
That task will probably need links to a bunch of things in the Git guide as well as the Issue guide: https://www.drupal.org/docs/develop/git https://www.drupal.org/docs/develop/issues (some can go into the Background Information field; some will be useful for some of the steps in the task)

Drupal.org
Git version control system
The Drupal open-source software project and community organizes itself into projects; most have an associated source code repository. Changes to the source code are tracked using the Git revision control system, and we use GitLab software to provide a web interface to Git and other features. Most changes to the source code are managed using issues on the drupal.org web site.
Sep 14th

Drupal.org
Drupal project issues
The Drupal project and community as a whole is composed of many smaller "projects", and each project uses "issues" to keep track of bugs, feature requests, tasks, and in some cases, support requests. Most people who contribute time to the Drupal project will eventually find themselves interacting with issues, so it is important to understand how they work and how the Drupal community uses them.
Jul 1st

rachel_norfolk  1 day ago
Will add some thoughts to the issue above
:thankful:
1

jhodgdon (she/her) Dec 1st at 9:08 AM
:two: Graphics for the Community and Contributor Guide areas -- @rachel_norfolk is leading this effort. Issue:
https://www.drupal.org/project/drupal_org_community/issues/3184840

Drupal.org
Add icons to Community and Contributor Guide
Problem/Motivation The Community and Contributor Guide landing pages, and the sub-pages of the Contributor Guide, are not all that visually appealing. We could use some icons on these pages to liven them up a bit... not enough to get in the way of the content, but enough to make the pages more visually appealing and add some tie-in here and there. Proposed resolution https://www.drupal.org/community -- Community landing page
Nov 25th




10 replies

rachel_norfolk  2 days ago
Yes - I’m trying to find a way to help increase legibility of the content (what is what, and how to easily navigate) with graphical elements. Probably more iconography than lots of illustrations.

rachel_norfolk  2 days ago
Would be interested to hear from people to whom this sounds an interesting challenge

jhodgdon (she/her)  2 days ago
It occurs to me that we have some graphics we can use, if we're looking for icons.

jhodgdon (she/her)  2 days ago
For example, https://www.drupal.org/about/core/strategic-initiatives each initiative has an icon of some sort

Drupal.org
Strategic Initiatives
The following are the strategic initiatives for Drupal core, in alphabetical order. For more details, and a full list of all high-priority efforts going on in Drupal core, see https://www.drupal.org/core/roadmap. See How are strategic initiatives chosen? for details on the selection process.
Oct 6th (39 kB)

rachel_norfolk  2 days ago
indeed. I did see a request the other day to add an icon field to projects, which would be interesting, too (edited) 

Carolyn Shannon  2 days ago
@rachel_norfolk I can mention this to the Pantheon Community folks who are participating in December’s Gift of Open Source; we might have some design/UX folks who would love to help w/this.

rachel_norfolk  2 days ago
yes please!

rachel_norfolk  2 days ago
it is especially UX we need

Carolyn Shannon  2 days ago
Will do.

Carolyn Shannon  2 days ago
I will send folks to the issue and let them know they can reach out in #documentation if interested. Sound ok?

jhodgdon (she/her) Dec 1st at 9:18 AM
:three:  Names of the "Official" and "Community" documentation areas
https://www.drupal.org/project/drupalorg/issues/3176075

Drupal.org
Consider renaming "Official" and "Community" documentation
Problem/Motivation This issue is the follow-up of a Twitter thread and a conversation in Slack.
Oct 9th




11 replies

rachel_norfolk  2 days ago
oh this is interesting - seen various feedback recently

jhodgdon (she/her)  2 days ago
This issue is about when you go to the Documentation landing page https://www.drupal.org/documentation

Drupal.org
Documentation
Drupal 8 documentation Community documentation for Drupal 8: general Drupal topics, contributed projects documentation. Drupal 8 User Guide Curated introduction to readers new to Drupal 8.
May 10th, 2018

jhodgdon (she/her)  2 days ago
You see "Official Guides" and "Community Guides"

jhodgdon (she/her)  2 days ago
It is confusing.

Carolyn Shannon  2 days ago
As a longtime contributor, it is very confusing to me.

jhodgdon (she/her)  2 days ago
What do you think of changing to "Curated Guides" and "Community Documentation"?

jhodgdon (she/her)  2 days ago
If people have more thoughts on this, either comment here or in the issue... eventually it has to get on the issue so we can actually make it happen. https://www.drupal.org/project/drupalorg/issues/3176075

Carolyn Shannon  2 days ago
Will do. I prefer that to “wiki”. To me, a wiki implies something amateur-ish, in the sense that it may be untrustworthy.

jhodgdon (she/her)  2 days ago
Please add that point of view to the issue. I have already commented about why I don't like the term "Wiki".
:ok:
1


jhodgdon (she/her)  2 days ago
We had a long discussion when we changed the name of documentation to "Community Documentation" in the first place... I should probably dig up that issue of multiple hundreds of comments. :) I think this is mostly about the term "Official" that probably needs to change.

jhodgdon (she/her)  2 days ago
https://www.drupal.org/project/documentation/issues/1278256

Drupal.org
Develop a plan to make it more clear that the current Documentation on drupal.org is community maintained.
Note: This issue is closed -- for follow-up comments, please use one of the other issues referenced in this summary. Thanks! Problem/Motivation The current Documentation on drupal.org is not well maintained, because it has grown to the point that it is not really maintainable by a formal Documentation Team: - Because anyone can edit and add pages, it grows into a pile of spaghetti, with a few nice meatballs of great content sprinkled throughout.
Sep 13th, 2011

jhodgdon (she/her) Dec 1st at 9:28 AM
:four: *Anything Else?*: What else do we need to talk about?




12 replies

rachel_norfolk  2 days ago
do we need to update the core calendar?

rachel_norfolk  2 days ago
(I have the magic permissions)

jhodgdon (she/her)  2 days ago
Yes, that would be good!

rachel_norfolk  2 days ago
can you describe the times here, just so I get them right?

jhodgdon (she/her)  2 days ago
First Tuesday of the month, at 9 AM US/Pacific (Los Angeles) time zone.

jhodgdon (she/her)  2 days ago
I don't want to say UTC because we'd have to adjust it when we get back to summer time. Sticking with US/Pacific keeps the time stable in North America and also Europe.

jhodgdon (she/her)  2 days ago
You'll get rid of the old entry for the Contributor Guide meetings right?

rachel_norfolk  1 day ago
The time is not stable between US and Europe - we change daylight savings at different times of year (and, indeed, countries in EU will soon scrap it altogether)

jhodgdon (she/her)  1 day ago
That is true, and we're trying to scrap Standard time here.

jhodgdon (she/her)  1 day ago
So are you advocating for having the official meeting time be in UTC?

rachel_norfolk  1 day ago
Yeah - I think I am

jhodgdon (she/her)  1 day ago
I just want to point out that the official time for the Contributor Guide meeting was listed as UTC but when we both changed back to standard time recently, we didn't honor the UTC time. But yeah I think I agree it's a better idea to have it be UTC. Less northern-hemisphere-centric.