Fedora-Council / council-docs

Clone
Source Code
GIT

#186 Issue #101. Re-arranged side menu; Updated help and join pages and added communications page
Merged 2 years ago by bcotton. Opened 2 years ago by karl0sfandang0.
Fedora-Council/ karl0sfandang0/council-docs issue101-convert-help-wiki  into  main

file modified
+3 -2 
@@ -1,9 +1,10 @@ 
 

  * xref:index.adoc[Mission and Foundations]
 

  * xref:leadership.adoc[Leadership]
 

- * xref:initiatives.adoc[Current Initiatives]
 

  * xref:orgchart.adoc[High-Level Organization]
 

  * xref:brand.adoc[Brand]
 

+ * xref:initiatives.adoc[Current Initiatives]
 

+ * xref:communications.adoc[Project Communications]
 

  * xref:code-of-conduct.adoc[Code of Conduct]
 

  ** xref:coc-clarifying.adoc[Clarifying Notes and Statements]
 

- * xref:help.adoc[Get Help]
 

+ * xref:help.adoc[Getting Help]
 

  * xref:join.adoc[Get Involved]

file added
+55 
@@ -0,0 +1,55 @@ 
 

+ = Communication in Fedora
 

+ 

+ As referenced on the xref:join.adoc[Get Involved] page below, Fedora is a massive global organisation with many people with different skills carrying out different roles. 

+ As you get involved you may need to find assistance and the xref:help.adoc[Getting Help] page can help you with that. 

+ This current page goes into more detail around the various communication channels within the Project.
 

+ 

+ == Primary Channels
 

+ 

+ === Chat
 

+ 

+ We now use https://chat.fedoraproject.org[Matrix/Element] as the primary synchronous channel to speak to each other in real time. 

+ 

+ You can find a list of the Fedora channels on Matrix https://chat.fedoraproject.org/#/room/#fedora-space:fedoraproject.org[here]. 

+ Most of these channels are mirrored on IRC at Libera Chat.
 

+ 

+ === Fedora Discussion 

+ 

+ https://discussion.fedoraproject.org/c/ask/6/none[Fedora Discussion] is the primary dicussion forum where you will find all the latest news & announcements, as well as discussion about open source projects; workflows, and Fedora-specific offerings such as the Fedora Editions.
 

+ See also under xref:help.adoc[Getting Help].
 

+ 

+ === Ask Fedora
 

+ 

+ https://discussion.fedoraproject.org/c/ask/6/none[Ask Fedora] sits within Fedora Discussion and  is the main community knowledge base and support forum hosted by the Fedora Project.
 

+ Ask Fedora is a good place to go for support and troubleshooting help, as mentioned on the xref:help.adoc[Getting Help] page.
 

+ 

+ 

+ == Other Communication Channels
 

+ 

+ As above, https://discussion.fedoraproject.org/c/ask/6/none[Fedora Discussion] is now the primary platform for longer asynchronous discussions where short-lived chats may not be enough. 

+ Some teams do still use mailing lists though.
 

+ The most significant mailing lists are:
 

+ 

+ * https://lists.fedoraproject.org/archives/list/announce@lists.fedoraproject.org/[announce]
 

+ * https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/[devel] 

+ * https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org/[devel-announce]
 

+ * https://lists.fedoraproject.org/archives/list/test@lists.fedoraproject.org/[test]
 

+ 

+ For a catalog of all the mailing lists look at https://lists.fedoraproject.org/[lists.fedoraproject.org]
 

+ 

+ https://fedoramagazine.org[Fedora Magazine] is a great resource for user-facing announcements and cool stories about usage, features, etc...
 

+ 

+ https://communityblog.fedoraproject.org[Fedora Community Blog] brings you contributor-facing announcements and updates. 

+ Within the Community Blog you'll also find https://communityblog.fedoraproject.org/tag/fridays-fedora-facts/[Friday's Fedora Facts]. 

+ These are weekly posts with status updates, schedule info, etc.. 

+ 

+ The Fedora Pagure source control repository allows posting of  https://pagure.io/Fedora-Council/council-docs/issues[issues] which can be discussed, assigned and remediated.  

+ Here you can raise issues or view, comment on, and request to act on open issues.
 

+ 

+ There are a number of official and other social media accounts, on various networks.
 

+ You can find details of these documented on the https://fedoraproject.org/wiki/Marketing_social_networks[Marketing Social Networks] Wiki page.
 

+ 

+ == Etiquette
 

+ 

+ In all our interactions, we aspire to _be excellent to each other_.
 

+ Read the xref:code-of-conduct.adoc[Code of Conduct] to learn more of what is expected of Fedora community members.

file modified
+26 -10 
@@ -1,17 +1,33 @@ 
 

  = Getting Help
 

+ There are several places to find help:
 

  

- == Ask Fedora 

- https://ask.fedoraproject.org/[Ask Fedora] is a community knowledge base and support forum hosted by the Fedora Project. 

+ == Quick Docs 

+ Firstly, https://docs.fedoraproject.org/en-US/quick-docs/[Fedora Quick Docs] is a collection of short HOWTO and FAQ style documentation for Fedora users. 

+ 

+ == Fedora Documentation
 

+ Then there is the https://docs.fedoraproject.org/en-US/docs/[official documentation].
 

+ Many answers can be found here.
 

+ If you don't find what you need in the documentation or you need more detail, you can ask a question via the forums below.
 

+ 

+ == Fedora Discussion
 

+ Fedora has a strong community that is ready to help you. 

+ Because users and contributors span the globe, a key element to the project is communication. 

+ See the xref:communications.adoc[Project Communications] page for more details.
 

+ 

+ https://discussion.fedoraproject.org/c/ask/6/none[Ask Fedora] is the main community knowledge base and support forum hosted by the Fedora Project within Fedora Discussion (below).
 

  Visit Ask Fedora for support and troubleshooting help.
 

  

+ Within https://discussion.fedoraproject.org/[Fedora Discussion] you will find all the latest news & announcments. 

+ It is also the place to talk about open source projects, workflows, and Fedora-specific offerings such as the Editions: 

+ Fedora Workstation, Fedora Server, Fedora CoreOS, Fedora Silverblue, and more....
 

+ 

  == Fedora Chat 

- Visit Fedora’s official chat platform, 

- https://chat.fedoraproject.org (powered by Matrix). 

+ https://chat.fedoraproject.org[Fedora’s official chat platform] (powered by Matrix) is the place to go for more synchronous, real time communication.
 

+ Fedora Chat on Matrix is the preferred platform for the future of Fedora Chat, however many of the Fedora Linux channels on IRC at Libera Chat are still bridged to Fedora Chat on Matrix to allow continued use of IRC during the transition.
 

  

- == Fedora Discussion
 

- https://discussion.fedoraproject.org/[Fedora Discussion] is a place to talk about open source projects, workflows, and Fedora-specific offerings
 

- such as Fedora Workstation, Fedora Server, Fedora CoreOS, 

- Fedora Silverblue, and more.
 

+ If you're interested in *why* Fedora's primary communications are moving to Matrix, check out https://www.youtube.com/watch?v=Z2A8BdU1gKg[this presentation] on the Fedora YouTube channel by Fedora Project Leader Matthew Miller.
 

  

- == Quick Docs 

- https://docs.fedoraproject.org/en-US/quick-docs/[Fedora Quick Docs] is a collection of short HOWTO and FAQ style documentation for Fedora users. 

+ == Bugzilla
 

+ If you believe you've found a bug you can report it through https://bugzilla.redhat.com/[Bugzilla]. 

+ The xref:quick-docs::bugzilla/index.adoc["Using Bugzilla"] page will give you any guidance you need to do this. 

+ You can also ask on https://discussion.fedoraproject.org/c/ask/6/none[Ask Fedora (as above)] to get advice on filing a good bug report.

file modified
+14 -14 
@@ -1,26 +1,28 @@ 
 

- = Get involved
 

+ = Get Involved
 

  

  Welcome to Fedora!
 

  

- This guide is intended for people that are interested in learning more about Fedora, perhaps with the intention of contributing to the community.
 

+ This guide is intended for people that are interested in learning more about Fedora, perhaps with the intention of getting involved and contributing to the community. 

+ 

+ You can refer to the xref:help.adoc[Getting Help] and xref:communications.adoc[Project Communications] pages for more specific information on how to find assistance via documentation and the various communication channels, such as Ask Fedora, and Fedora Chat (powered by Matrix).
 

  

  == What is Fedora?
 

  

- The Fedora project is a community of people working together to build a Free and Open Source software platform: link:https://getfedora.org[the Fedora Operating System], and its various editions.
 

- You can learn more about Fedora, our mission, our four foundations, our leadership, our current Communitiy Initiatives, and how we are organised using the pages linked to in the left hand sidebar.
 

+ As described under xref:index.adoc[Mission and Foundations], the Fedora Project is a community of people working together to build a Free and Open Source software platform: 

+ the https://getfedora.org[Fedora Operating System], and its various editions.
 

+ You can learn more about the Project; our leadership; brand; current Communitiy Initiatives and how we are organised using the pages linked in the left hand sidebar.
 

+ 

  

  If you are looking to contribute and already have an idea of how and what to do, go ahead and get started!
 

  If you are not so sure, read on.
 

  

- == Communication in Fedora
 

+ == Contributing to Fedora
 

  

  Fedora is a xref:orgchart.adoc[massive global organisation] where people with many different skills carry out xref:fedora-join::index.adoc[different roles] to keep the community ticking along.
 

- All services used by the Fedora community are linked to a central Fedora account that you can get link:https://accounts.fedoraproject.org/[here].
 

- We use link:https://chat.fedoraproject.org[Matrix/Element] and/or link:https://fedoraproject.org/wiki/Communicating_and_getting_help?rd=Communicate#IRC[IRC] to speak to each other in real time and link:https://fedoraproject.org/wiki/Communicating_and_getting_help?rd=Communicate#Mailing_Lists[mailing lists] for longer discussions for which short live chats may not be enough.
 

- 

- In all our interactions, we aspire to _be excellent to each other_.
 

- Read the xref:code-of-conduct.adoc[Code of Conduct] to learn more of what is expected of Fedora community members.
 

+ All services used by the Fedora community are linked to a central Fedora account.
 

+ If you're intending to get involved you should get one https://accounts.fedoraproject.org/[here].
 

  

+ There is an excellent https://fedoramagazine.org/how-to-contribute-to-fedora/[article in Fedora Magazine] covering in some detail the various ways you might get started.
 

  

  == Not sure where to start? Come hang out with us!
 

  
@@ -28,11 +30,9 @@ 
 

  There is far too much happening in Fedora all the time---even we find it hard to keep up with it all!
 

  So, if you are not sure of where to begin or have any queries at all, come hang out with the xref:fedora-join::index.adoc[Fedora Join Special Interest Group (SIG)] on any of our channels:
 

  

- - Email: link:https://lists.fedoraproject.org/admin/lists/fedora-join@lists.fedoraproject.org/[Fedora Join mailing list],
 

- - Chat (over Matrix/Element): link:https://matrix.to/#/%23join:fedoraproject.org?web-instance%5Belement.io%5D%3Dchat.fedoraproject.org[Fedora Join on Matrix/Element],
 

- - Chat (over IRC): link:ircs://irc.libera.chat:6697/%23fedora-join[#fedora-join] on link:https://libera.chat/[Libera.Chat],
 

- - Chat (over Telegram): link:https://t.me/joinfedora[Fedora Join Telegram group].
 

+ - Chat (over Matrix/Element): https://chat.fedoraproject.org/#/room/#join:fedoraproject.org[Join Fedora on Matrix/Element],
 

  

+ - Email: https://lists.fedoraproject.org/archives/list/fedora-join@lists.fedoraproject.org/[Fedora Join mailing list],
 

  

  Here, you can speak to community members and other newcomers while we explore Fedora together.
 

  We will help you learn the systems and processes that the Fedora community uses, and as you gain a better idea of where you would like to contribute, we will also help you learn the skills that you may need.

Fix for Issue #101 - 1st Draft. nav.adoc, pages/help.adoc and pages/join.adoc all updated; pages/communications.adoc added.

rebased onto 93e4b9c
2 years ago

One sentence per line.

Also, maybe we should omit the context on why this decision was made for this page? I also see us pointing a lot of newcomers to this page, and I feel like it is is extraneous information for most people.

One sentence per line.

Also, I would prefer that we omit Telegram entirely. The bridges are in an unstable state and I would prefer to avoid emphasizing our bridged platforms in general. At some point in the long-term future, we may consider removing the bridges.

One sentence per line.

Also a minor typo: s/announcments/announcements/

I'm thinking that mailing lists should not be listed as a primary communication channel, but instead in the other channels section below. This primary section also omits any mention of Fedora Discussion other than the line about Fedora Ask. Ultimately, we really want to drive more people and traffic to Fedora Discussion as much as possible. This is the direction we want to move, also as part of our ongoing 5-year strategy to modernize our communication platforms.

@mattdm might also have thoughts about how exactly we word the mailing list piece? But at the very least, I'd prefer to not elevate the lists as a primary communication channel. We should mention something about Fedora Discussion here instead.

One sentence per line.

This is a tough one though. Should we mention Pagure here as a communication platform? Together with GitLab, these are common platforms for specific teams, working groups, and SIGs to discuss active work and tasks. But usually, this is for specific projects. I'm undecided on how we should explain Pagure and GitLab, and whether they should fit into this document at all. @bcotton @bookwar @sumantrom @dcantrell, any thoughts on this one?

Given the emergence of Ask Fedora, should we still list this community? It definitely seems active and people do go there to get questions answered. While I don't think they officially follow the Fedora Code of Conduct, they do have their own form of a code of conduct and forum etiquette, which seems sufficiently close to the Fedora CoC at a very cursory glance.

I'm not sure what is right to do here or not. I don't want to invalidate the heroic work of supporting people using Fedora and doing Q&A work. Maybe we could pad this text with more of an explanation, or add a disclaimer that the experience in this community is separate from the Fedora community? For example, if someone misbehaves there to a user or contributor and it is not handled by a platform moderator, realistically there isn't anything we could do about it.

Metadata Update from @jflory7:
- Pull-request tagged with: type - existing docs, type - new docs
2 years ago

Instead of listing Twitter, Reddit, and Discord here explicitly, I'd rather link to the Marketing social networks wiki page, which is more up-to-date on these kinds of things:

https://fedoraproject.org/wiki/Marketing_social_networks

One sentence per line.

Also, perhaps we should link directly to https://docs.fedoraproject.org/en-US/quick-docs/bugzilla/ ? If yes, let's use a xref here. I think it would be xref:quick-docs::bugzilla/index.adoc[Fedora Quick Docs]

This link is long. Any reason we cannot use https://fedoramagazine.org/how-to-contribute-to-fedora/ by itself? The extra text= parameter has no effect for me in Firefox.

@karl0sfandang0 Hey, a kudos for tackling #101! The wiki page you started with is an ancient page and there was so much information to crawl through and figure out if it was meaningful. I left some feedback inline above, but I want to add that your work is really appreciated and this is a page that we really need updated in Fedora. So, thank you for your work on this! :pray:

Hi @ankursinha, @alciregi, @t0xic0der, @bt0dotninja, @kevin, et al, if you have some free time, here is a Pull Request that we could really use your feedback on!

This will replace the Communicating and getting help wiki page once it goes live. Getting it right will be important so we can use this as a meaningful place to direct newcomers and old-timers alike about the best ways to get help and communicate with other Fedora folks across the community. Since you all are either Join SIG members or long-time Fedorans, you have a lot to offer here.

You can always pull down these changes locally and build the Fedora docs site locally, but an easier way to review this might be by using the Asciidoctor.js Live Preview for your browser and viewing each page from the browser (see add-on for Firefox, Chrome, Edge). Once you have the add-on installed, you can navigate to the specific pages:

I think that we should keep from using Pagure as a communication platform to better establish our move to GitLab for projects and Discussions for conversations.

It should be fine if we make it clear that this is an external support community.

I wonder if it begs us to ask the question or better define what an external support community is, their limits, etc.

+1 to this.

Pretty sure we would miss changing it everywhere consistently if a change were to happen so its just better to have it all in one designated place.

I agree with almost all @jflory7 's comments. ;)

I'd suggest for mailing lists we should just describe the current state (most dicussion is on discuss, but some communications still happen on lists), and then we can adjust it in another PR later when appropriate. I'd like to get this live instead of lingering on that. :)

Anyhow, many thanks for writing this up!!!

I'm thinking that mailing lists should not be listed as a primary communication channel, but instead in the other channels section below. This primary section also omits any mention of Fedora Discussion other than the line about Fedora Ask. Ultimately, we really want to drive more people and traffic to Fedora Discussion as much as possible. This is the direction we want to move, also as part of our ongoing 5-year strategy to modernize our communication platforms.

Agreed-ish. We should keep those announcement lists where they are, but focus on Discussion. Something like "We use Fedora Discussion for blah blah blah blah. Some teams and announcements still use mailing lists. A few key lists are:"

This is a tough one though. Should we mention Pagure here as a communication platform?

I'm okay with it in this context.

Given the emergence of Ask Fedora, should we still list [the Fedora Forums] community?

No.

Thank you for the input everyone. I will take it all into account in another pass at this as soon as possible.

I'm thinking that mailing lists should not be listed as a primary communication channel, but instead in the other channels section below. This primary section also omits any mention of Fedora Discussion other than the line about Fedora Ask. Ultimately, we really want to drive more people and traffic to Fedora Discussion as much as possible. This is the direction we want to move, also as part of our ongoing 5-year strategy to modernize our communication platforms.

Agreed-ish. We should keep those announcement lists where they are, but focus on Discussion. Something like "We use Fedora Discussion for blah blah blah blah. Some teams and announcements still use mailing lists. A few key lists are:"

This is a tough one though. Should we mention Pagure here as a communication platform?

I'm okay with it in this context.

Given the emergence of Ask Fedora, should we still list [the Fedora Forums] community?

No.

OK. I've kept the Pagure bit in but moved it down, and I've removed the bit about Fedora Forums.

rebased onto 1a14eae
2 years ago

This is in substantially good shape. We can make further edits afterward if needed. Thanks, @karl0sfandang0

Pull-Request has been merged by bcotton
2 years ago
Metadata
None

type - new docs type - existing docs

Changes Summary 4
+3 -2
file changed
project/modules/ROOT/nav.adoc
+55
file added
project/modules/ROOT/pages/communications.adoc
+26 -10
file changed
project/modules/ROOT/pages/help.adoc
+14 -14
file changed
project/modules/ROOT/pages/join.adoc
Powered by Pagure 5.14.1
Documentation • File an Issue • About • SSH Hostkey/Fingerprint
© Red Hat, Inc. and others.