PR#110: docs: Refactor/rewrite of "Get involved" page - fedora-diversity

fedora-diversity

#110 docs: Refactor/rewrite of "Get involved" page

Merged 4 years ago by jflory7. Opened 4 years ago by jflory7.

jflory7/fedora-diversity change/join-docs into master

docs: Update build/preview scripts from upstream

Justin W. Flory • 4 years ago

1e19c11

docs: Refactor/rewrite of "Get involved" page

Justin W. Flory • 4 years ago

b1633f7

docs: Move get-involved page to top level of navbar

Justin W. Flory • 4 years ago

20e3a7e

build.sh

file modified

+35 -5

		`@@ -1,16 +1,46 @@`
		`#!/bin/sh`

		`+ image="docker.io/antora/antora"`
		`+ cmd="--html-url-extension-style=indexify site.yml"`
		`+`
		`if [ "$(uname)" == "Darwin" ]; then`
		`# Running on macOS.`
		`# Let's assume that the user has the Docker CE installed`
		`# which doesn't require a root password.`
		`- docker run --rm -it -v $(pwd):/antora antora/antora --html-url-extension-style=indexify site.yml`
		`+ echo ""`
		`+ echo "This build script is using Docker container runtime to run the build in an isolated environment."`
		`+ echo ""`
		`+ docker run --rm -it -v $(pwd):/antora $image $cmd`

		`elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then`
		`# Running on Linux.`
		`- # Let's assume that it's running the Docker deamon`
		`+ # Check whether podman is available, else faill back to docker`
		`# which requires root.`
		`- echo ""`
		`- echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it."`
		`- sudo docker run --rm -it -v $(pwd):/antora:z antora/antora --html-url-extension-style=indexify site.yml`
		`+`
		`+ if [ -f /usr/bin/podman ]; then`
		`+ echo ""`
		`+ echo "This build script is using Podman to run the build in an isolated environment."`
		`+ echo ""`
		`+ podman run --rm -it -v $(pwd):/antora:z $image $cmd`
		`+`
		`+ elif [ -f /usr/bin/docker ]; then`
		`+ echo ""`
		`+ echo "This build script is using Docker to run the build in an isolated environment."`
		`+ echo ""`
		`+`
		`+ if groups \| grep -wq "docker"; then`
		`+ docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`+ else`
		`+ echo ""`
		`+ echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password."`
		`+ echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/."`
		`+ echo ""`
		`+ sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd`
		`+ fi`
		`+ else`
		`+ echo ""`
		`+ echo "Error: Container runtime haven't been found on your system. Fix it by:"`
		`+ echo "$ sudo dnf install podman"`
		`+ exit 1`
		`+ fi`
		`fi`

modules/ROOT/nav.adoc

file modified

+1 -2

		`@@ -4,5 +4,4 @@`
		`* Fedora Women's Day (FWD)`
		`** xref:fedora-womens-day/about.adoc[About FWD]`
		`** xref:fedora-womens-day/resource-pack.adoc[Resource pack]`
		`- * How to contribute`
		`- ** xref:contribute/join.adoc[Join the team]`
		`+ * xref:get-involved.adoc[Get involved]`

modules/ROOT/pages/contribute/join.adoc

file removed

-96

		`@@ -1,96 +0,0 @@`
		`- = Join Fedora Diversity and Inclusion Team`
		`-`
		`- If you're interested in helping with the Fedora Diversity and Inclusion Team, please complete the following steps to become a member.`
		`-`
		`-`
		`- [[create-fas-account]]`
		`- == Create an FAS account`
		`-`
		`- In order to contribute to Fedora, you will need to create a link:Account_System[FAS account] and sign the Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement], if you have not already.`
		`- You can do this through the link:Infrastructure/AccountSystem[Fedora Account System].`
		`-`
		`-`
		`- [[update-wiki]]`
		`- == Update your wiki homepage`
		`-`
		`- Use your link:Account_System[Account System] to login and start adding content to your homepage.`
		`- It's recommended you put some of your activity or involvement, inside or outside of Fedora, on this page.`
		`- It's helpful for others to know more about you, what you are involved with in the project, and more.`
		`-`
		`-`
		`- [[mailing-list]]`
		`- == Join the mailing list`
		`-`
		`- To join the mailing list, you must subscribe on https://lists.fedoraproject.org/admin/lists/diversity.lists.fedoraproject.org[lists.fedoraproject.org].`
		`- Our mailing list is a key part of how Diversity communicates, and a lot of important news and discussion are shared through our mailing list.`
		`-`
		`-`
		`- [[self-introduction]]`
		`- == Send a self-introduction`
		`-`
		`- Send a self-introduction to the mailto:diversity@lists.fedoraproject.org[Diversity mailing list] explaining a bit about yourself.`
		`- This is one of the most helpful steps for the rest of the Diversity and Inclusion Team members.`
		`- When introducing yourself, here's some key points to make sure to include in your introduction:`
		`-`
		`- * Are you new to contributing to Fedora?`
		`- If so, tell us why you're interested in contributing or what interests you most.`
		`- * Are you from another community?`
		`- Tell us about your role and what you're doing in those other communities.`
		`- * Already an active contributor?`
		`- Share what other areas of Fedora you are working in and your role in the Project.`
		`- * Involved with any local events or programs?`
		`- If you do any in-person advocacy for Linux, Fedora, or diversity in tech, tell us about how you're involved.`
		`- (Also consider adding your event to the link:Diversity_Events[Diversity Events] wiki page!)`
		`- * What interests you in the Diversity and Inclusion Team?`
		`- What are your interests for wanting to become involved or what motivates you up to want to participate?`
		`-`
		`-`
		`- [[join-irc-telegram]]`
		`- == Join #fedora-diversity on IRC or Telegram`
		`-`
		`- Your next step should be to join the https://webchat.freenode.net/?channels=#fedora-diversity[#fedora-diversity] IRC channel on the FreeNode IRC network.`
		`- A lot of our discussion and planning happens in real-time on IRC, and it's the best place to meet some of the team and get a view of what's happening with the Diversity and Inclusion Team.`
		`-`
		`-`
		`- [[first-steps]]`
		`- == Make your first steps`
		`-`
		`- See xref:commops::first-steps.adoc[Make your first steps in Fedora] for more info.`
		`-`
		`-`
		`- [[attend-meeting]]`
		`- == Attend a meeting`
		`-`
		`- A lot of action happens at the https://apps.fedoraproject.org/calendar/diversity-team/[bi-monthly meetings].`
		`- Attend a Fedora https://apps.fedoraproject.org/calendar/diversity-team/[Diversity and Inclusion Team meeting] and introduce yourself during roll call!`
		`-`
		`- Every week, the Diversity and Inclusion team comes together to discuss https://pagure.io/fedora-diversity/issues?tags=meeting[items on our agenda] and check in on the tasks that everyone is working on.`
		`- Introducing yourself during roll call is another great way to get involved and will let others know you are part of the meeting.`
		`-`
		`-`
		`- [[get-your-hands-dirty]]`
		`- == Get your hands dirty`
		`-`
		`- Now, you should begin finding a task to work on.`
		`- All Diversity-related tasks are mapped out in our https://pagure.io/fedora-diversity/issues[Pagure repository].`
		`-`
		`- Tasks, problems, or objectives are added as "issues" to the https://pagure.io/fedora-diversity/issues[fedora-diversity repository on`
		`- Pagure].`
		`- Check and see https://pagure.io/fedora-diversity/issues?tags=meeting[what D&I is working on now] to see what is happening this week.`
		`-`
		`- After that, look at all of the https://pagure.io/fedora-diversity/issues[open tickets] on our https://pagure.io/fedora-diversity/[Pagure repository].`
		`- See something that looks interesting?`
		`- Be sure to leave a comment and feedback if possible.`
		`- Check if the ticket has an owner.`
		`- If it doesn't, you can step up and take ownership!`
		`- If it does, contact the owner of the ticket and see if they need any help.`
		`- This also provides a great opportunity to get mentorship and help with getting started on a new task!`
		`-`
		`-`
		`- [[join-fas-group]]`
		`- == Join the FAS group`
		`-`
		`- After completing or beginning all of the above steps, you can apply for membership in the https://admin.fedoraproject.org/accounts/group/view/diversity-team[Diversity and Inclusion Team FAS group].`
		`-`
		`- In the beginning of your time contributing, you will remain pending in the group.`
		`- After staying involved with Diversity for a while and helping out with tasks, your membership will be approved.`

modules/ROOT/pages/get-involved.adoc

file added

+107

		`@@ -0,0 +1,107 @@`
		`+ = Get involved with Fedora Diversity and Inclusion Team`
		`+`
		`+ Interested in helping the Fedora Diversity and Inclusion Team?`
		`+ This page explains the typical process for getting involved with our team.`
		`+`
		`+`
		`+ [[create-fas-account]]`
		`+ == Create Fedora Account System (FAS) account`
		`+`
		`+ All contributors to Fedora need to register in the https://admin.fedoraproject.org/accounts/[Fedora Account System].`
		`+ New contributors are asked to sign the https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement[Fedora Project Contributor Agreement] (FPCA).`
		`+ This is not a copyright assignment agreement, but ensures your contributions to Fedora have acceptable licensing terms.`
		`+ If you need help with this, contact the https://fedoraproject.org/wiki/Infrastructure#Communicating[Fedora Infrastructure Team].`
		`+`
		`+`
		`+ [[mailing-list]]`
		`+ == Join the mailing list`
		`+`
		`+ https://lists.fedoraproject.org/admin/lists/diversity.lists.fedoraproject.org[Subscribe here!]`
		`+`
		`+ The Fedora Diversity and Inclusion Team uses a mailing list.`
		`+ The mailing list is used for announcements, summaries of meetings, and a way to share longer-form content with the team.`
		`+ It is a good place to keep up with what we are up to!`
		`+ To join the mailing list, subscribe on https://lists.fedoraproject.org/admin/lists/diversity.lists.fedoraproject.org[lists.fedoraproject.org].`
		`+`
		`+`
		`+ [[self-introduction]]`
		`+ == Send a self-introduction`
		`+`
		`+ If you want to get involved, we want to get to know you!`
		`+ So don't be shy, send an introduction on our mailing list.`
		`+ This is a helpful step for other folks on the team to get to know you.`
		`+`
		`+ Not sure what to say?`
		`+ Does writing an introduction feel awkward?`
		`+ Consider these questions when introducing yourself:`
		`+`
		`+ * Are you new to the Fedora community?`
		`+ If so, what was interesting to you about Fedora?`
		`+ * Are you involved with other communities?`
		`+ Tell us about what you do in other communities or projects.`
		`+ * Do you already contribute to Fedora?`
		`+ Let us know what parts of Fedora you are involved in.`
		`+ * Are you an organizer of local events or programs?`
		`+ If you run any kind of event in your local community, let us know what you do.`
		`+ * What is interesting to you about the Fedora Diversity and Inclusion Team?`
		`+ Our team is a collection of people with different interests and niches.`
		`+ Knowing each others' interests and what we like lets us connect each other to things we want to help out with.`
		`+`
		`+`
		`+ [[join-irc-telegram]]`
		`+ == Join IRC/Telegram group chat`
		`+`
		`+ The Fedora Diversity and Inclusion Team has a real-time group chat.`
		`+ We use this group chat for quick updates, friendly chatter, and running meetings.`
		`+ We use both an IRC channel on the https://freenode.net/[Freenode IRC network] and a Telegram chat group.`
		`+ Both are bridged to each other, so folks in IRC will see Telegram messages and vice versa.`
		`+`
		`+ Here are the easiest ways to join:`
		`+`
		`+ * IRC`
		+ ** link:ircs://chat.freenode.net:6697/%23fedora-diversity[`chat.freenode.net/#fedora-diversity`]
		`+ ** https://webchat.freenode.net/?channels=#fedora-diversity[Web chat]`
		`+ * https://t.me/fedoradiversity[Telegram]`
		`+`
		`+ Don't forget to say hi when you join!`
		`+`
		`+`
		`+ [[first-steps]]`
		`+ == Make your first steps`
		`+`
		`+ See xref:commops::contribute/first-steps.adoc[Make your first steps in Fedora] for more info.`
		`+`
		`+`
		`+ [[attend-meeting]]`
		`+ == Attend a meeting`
		`+`
		`+ https://apps.fedoraproject.org/calendar/diversity-team/[Find our next meeting on our calendar!]`
		`+`
		`+ The team usually holds a weekly meeting over IRC/Telegram to review on-going work and determine next steps on current work.`
		`+ The meeting format is intended to be quick updates instead of long discussion.`
		`+ It is a good opportunity to say hello and meet other members of the team in real-time.`
		`+`
		`+`
		`+ [[tickets]]`
		`+ == Check out Pagure tickets`
		`+`
		`+ The next step to get involved is to review our ticket tracker and look for something interesting to you.`
		`+ All of our open tickets are in our https://pagure.io/fedora-diversity/issues[Pagure repository].`
		`+ New tasks are added as "issues" into the Pagure repository.`
		`+`
		`+ Here is a quick index of different types of tickets:`
		`+`
		`+ * https://pagure.io/fedora-diversity/issues?status=Open&priority=20[Meeting tickets]`
		`+ * https://pagure.io/fedora-diversity/issues?status=Open&tags=good+first+issue[Good first tickets for newcomers]`
		`+ * https://pagure.io/fedora-diversity/roadmap[Roadmap] (collection of tickets around specific objectives or goals)`
		`+`
		`+ See a ticket that looks interesting?`
		`+ If someone is not already assigned, leave a comment and ask how you can help.`
		`+ Another member of the team will get back to you with some feedback on how you get help.`
		`+ This is one opportunity to get mentorship and help with getting started on a task.`
		`+`
		`+ Alternatively, do you think something is missing or could be improved in the Fedora community?`
		`+ Open a new ticket with your idea or suggestion.`
		`+ Our best ideas come from a wide range of people with different backgrounds, experiences, and perspectives.`
		`+ Whether you are new to the Fedora community or are a long-time contributor, you might have the next great idea for the team.`
		`+ Open a new ticket and we can discuss more about your idea or suggestion.`

preview.sh

file modified

+6 -6

		`@@ -5,14 +5,14 @@`
		`# Let's assume that the user has the Docker CE installed`
		`# which doesn't require a root password.`
		`echo "The preview will be available at http://localhost:8080/"`
		`- docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx`
		`+ docker run --rm -v $(pwd):/antora:ro -v $(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro -p 8080:80 nginx`

		`elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then`
		`# Running on Linux.`
		`- # Let's assume that it's running the Docker deamon`
		`- # which requires root.`
		`+ # Fedora Workstation has python3 installed as a default, so using that`
		`echo ""`
		`- echo "This build script is using Docker to run the build in an isolated environment. You might be asked for a root password in order to start it."`
		`- echo "The preview will be available at http://localhost:8080/"`
		`- sudo docker run --rm -v $(pwd)/public:/usr/share/nginx/html:ro -p 8080:80 nginx`
		`+ echo "The preview is available at http://localhost:8080"`
		`+ echo ""`
		`+ cd ./public`
		`+ python3 -m http.server 8080`
		`fi`

jflory7 commented 4 years ago

This commit is a significant rewrite of our "Get involved" page. I expanded some parts, rewrote some parts to be more clear, fixed a lot of URLs, and removed some parts that are not a major part of actually getting involved as a team member. My edits are briefly explained below:

Create FAS account: Fix links, try to better explain why this is important/necessary
Wiki homepage: Realistically the wiki homepage is not critical and there are new barriers to editing the wiki because of anti-spam measures (CLA+1 required)
Mailing list: Better explain how we use our mailing list
Self-introduction: Attempted to make questions feel more genuinely curious - they felt a little intimidating to me in retrospect!
Group chat: Properly explain IRC/Telegram, add links to join either
First steps: Fix xref to CommOps docs
Meetings: Better explain how our meetings work as of 2019
Pagure tickets: Clarify our workflow for 2019, update/fix URLs, and emphasize importance of new ideas into the mix too :)
FAS group: Drop this completely, it is not a major part of our everyday work and the group is invite-only now anyways (i.e. nobody can join the group on their own anymore)

Metadata Update from @jflory7:
- Pull-request tagged with: improvement, type - docs, type - onboarding

4 years ago

jflory7 commented 4 years ago

Here is a screenshot of the rendered change on my local workstation. Note the CommOps page will not render because I only built the Fedora D&I team docs, not the whole Fedora Docs site:

amsharma commented 4 years ago

Why make your first step is pointing to commops page?

jflory7 commented 4 years ago

Why make your first step is pointing to commops page?

It links to this page:

https://docs.fedoraproject.org/en-US/commops/contribute/first-steps/

This page suggests good beginner Fedora Badges for someone to earn, for any team or sub-project. Since it was already written there, I thought it was better to link to the existing page instead of duplicating content.

amsharma commented 4 years ago

Why make your first step is pointing to commops page?

It links to this page:
https://docs.fedoraproject.org/en-US/commops/contribute/first-steps/
This page suggests good beginner Fedora Badges for someone to earn, for any team or sub-project. Since it was already written there, I thought it was better to link to the existing page instead of duplicating content.

Ok great. I am +1 for the change.
At the sametime, do you think if this page is generic than there can be a better place for this page, more visible?