#159 Run a "Write the Docs" event targeting Fedora support groups
Opened 5 years ago by jflory7. Modified 4 months ago


Run a 2-3 "hackathon"-style event to improve Fedora quick docs, targeting Fedora support groups to help improve Fedora's documentation


There's several knowledgeable people in all of our support groups. They get a lot of feedback from users and they are usually the first ones to help someone find a fix. A great pool of knowledgeable writers for things like quickdocs could be from this pool of people who spend so much time already answering a "live support"-style version of the content already in quickdocs.

I was thinking of ways to mobilize this group of people to contribute to something like quickdocs, so it could be a unified place of reference for all of our support groups, even ones we don't have actual Fedora contributors in (kind of a cool way to insure giving up firmness in letting people self-organize things like this with our name).


What it looks like

I see this as a two or three day sprint to encourage new contributors and contributions to Fedora Quick Docs. We need to connect with the Fedora Docs team (e.g. @bex @zoglesby @jsmith @pbokoc @pmkovar et al) to create "easy-fix" style tasks and issues for things to work on, or make it as simple as possible about how someone could write and contribute a new quick doc for a topic we aren't covering.

We would ask contributors to help improve our quick docs or add missing topics for things they normally find themselves supporting.


Outreach to our support communities is essential. This is a unique group of people who not only have a lot of knowledge about Fedora, but also the questions people ask. Their perspective from the support end is valuable because they directly understand user needs or interests, and can help us make our documentation more relevant for more people.

The format of quick docs as topic-based documents makes this easier too.


I see badges playing an influential role here. I suggest creating multiple versions of the same badge for various support communities we want to target (e.g. Reddit, Discord, Telegram, FedoraForums, etc.). Then, someone who contributes could claim to "come" from one of these communities by linking their profile or showing some sort of verification of their membership, and we would award them the Quickdocs Hackathon badge for their support platform. This would be an extra motivational step to try and get people to jump on-board (e.g. a special badge for Telegram users only to get might be more unique and special to earn than a general badge – the idea of selective targeting).


  • Improved topic-based documents that better represent what people are searching for and want to know about Fedora
  • Better quality of existing topics based on recent support encounters
  • Better awareness of quick-docs themselves by people across various support communities (more likely to use them as a reference when offering support to users)

I talked about this with @bex last week, and he mentioned that some of these items (not necessarily all) should be in place before running the event:

  • Antora toolchain running and launched (also blocking #148)
  • Improved quickdocs navigation
  • Draft site generation
  • New Fedora Infrastructure technical writer started (starts in 2.5 months)
  • Automated publishing of docs (this could take a while, so maybe we can skip this one)

I think this is blocked by Antora and possibly the improved quickdocs navigation, but curious to know what others think about it.

Metadata Update from @jflory7:
- Issue untagged with: help wanted
- Issue tagged with: blocked

5 years ago

Any help needed with this?

Metadata Update from @jflory7:
- Issue tagged with: team - docs

5 years ago

Metadata Update from @jflory7:
- Issue untagged with: blocked
- Issue priority set to: needs review (was: waiting on external)
- Issue set to the milestone: Future releases (was: Fedora 29 (to Oct. 2018))

5 years ago

Discussed in 2018-10-10 meeting.

We learned the Join SIG was discussing similar types of things. We decided to start a new Discourse thread and share it with the Join SIG and Docs mailing lists, to invite people to participate on planning it out. If we have enough interested people to plan and lead this, we could try to start on it before 2019.

The Discourse thread is here:


Discussed in 2018-11-21 meeting.

In the meeting, we agreed to put this ticket on target for completion during the Fedora 30 release cycle. We didn't get much farther in the planning during yesterday's meeting, but we'll advance further on this over the next month or two. First steps will include some requirements gathering and figuring out the best way to approach this first.

We've had a lively discussion already over on Discourse around this topic.

Metadata Update from @jflory7:
- Issue set to the milestone: Fedora 30 (to May 2019) (was: Future releases)

5 years ago

Metadata Update from @jflory7:
- Issue priority set to: next meeting (was: needs review)

5 years ago

Discussed in 2018-11-28 meeting.

Next steps for this ticket are requirements / information gathering. Before running an event around contributing to Fedora Docs, we want to know: how hard is it exactly to contribute to Docs today? How we can we improve the user experience in tooling? If we can't solve it in tooling, what documentation is needed to better the contributor experience?

We decided on the following:

  1. Run user tests to make note of difficult points in contributing to docs
  2. Collect intro materials like videos and contribution guidelines

I'm going to draft up a few test scenarios and open new tickets for them by the next meeting. At the meeting, we will try to find volunteers to run through some of the test cases and gather feedback.

Once the new tickets are filed, I also want to start a conversation with the Design Team to collect feedback. These new tickets could be included in the article @bt0dotninja is putting together in #186.

So, one thing of note: even if this happens in March 2019 or later, it'd be ideal to largely fund it from the 2018 budget (because I don't think the Fedora logo refresh is going to be ready in time for the large order of swag and branded things in this FY).

Discussed in 2018-12-04 meeting and 2018-12-12 meeting.

The last two meetings covered ideas on improving the on-boarding experience for new docs writers and how to make the event more engaging / attractive for new contributors by game-ifying it.

And @mattdm, maybe we will inquire for budget after all. :smile: I hadn't thought about it, but it organically came up in today's meeting.

Next steps

  • @jflory7: Draft set of user testing scenarios for contributing to docs, create new tickets for each test scenario, ask for Design Team feedback. Due: before 2019
  • @blaise: Create a flowchart based on 2018-12-04 meeting discussion (around conventions / expectations for filing a CommOps ticket), ready for review by Wed, Dec. 19th
  • @bt0dotninja: File a new ticket to create a "Fedora jargon" cheatsheet, to help explain different terms and phrases often used in Fedora (but not obvious to a newcomer or first-timer) by Wed, Dec. 19th
  • @blaise: File a new ticket to better document procedure and best practices on cross-team communication and collaboration by Wed, Dec. 19th (and maybe add the flowchart from previous action there once it is ready!)
  • @meskarune: File a new ticket for a "cheatsheet" to explain different Fedora tools, apps, and resources and how they are used, by Wed, Dec. 19th
  • @meskarune: File a new ticket for brainstorming docs event "competition" categories and possible prizes to go with them, by Wed, Dec. 19th

Other ideas

  • @meskarune: “Game-ifying” a docs event, possibly having teams to compete for different goals (e.g. “edit X number of pages”, “create X number of new pages”, etc.)
  • @blaise: Offering prizes for different categories, e.g. UnixStickers swag, gift cards, etc.
  • @blaise: Using Badges to correspond with some of the competition categories? (e.g. "Most docs edited in 2019 contribute-athon event", "Most new pages created in 2019 contribute-athon event", etc.)
  • @blaise: Using page views / metrics as an incentive for a "highest visibility" fix category?

Login to comment on this ticket.