Fedora Docs community contribution hack-fest with user communities

fedora-documentation

#1

In today’s meeting, we revisited ticket #159 on organizing a Fedora Docs hack-fest to encourage new contributions to Fedora’s Quick Docs user documentation. We wanted to open a cross-team conversation with Fedora Docs and the Join SIG (especially since the Join SIG has recently had discussion on similar ideas).

Quick summary

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

Background

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).

More info

See ticket #159 for more details.

How to move forward on this

It would be nice to have 2-3 people working on this together, since both outreach and planning for engagement are equally important to be successful. Some implementation ideas are in the ticket already, but I wanted to open up some discussion about this and maybe consider things we can start doing today to make this idea possible.

I was planning to take on this ticket in 2019, but I’m happy to support others in working on this and to provide advice and guidance where necessary (but I won’t have time to lead on this before 2019).

What do others think about this idea? Is it a good idea or too crazy? What can we do to start making it happen?


#2

I will start adding some stuff to that documentation when it has a search button. :smiley:


#3

I believe that Adam, Igor, and Ben are talking about trying something like this after Devconf.cz. Perhaps we should use that as our first event to build the model before we try to find groups and plan 2-3 out?


#4

This is a real issue. Adam is working on it, however we could use some help. Do you have time?


#5

Do you mean for us to begin planning at DevConf or to do an in-person hackfest somewhere like DevConf? I’m curious to understand what you mean, since the idea we have in CommOps mostly focuses on online user support communities.


#6

I have a few suggestions for things to do:

  • Release Notes need an overhaul. Right now we focus on basically covering Changes, which are already covered on the Wiki through Change pages. That’s not necessarily a bad thing, but we’re missing a lot of stuff that is important to users but isn’t a change. Things like "what version of " ships with Fedora XX at release. Ideally we’d put together a list of these components and link to their upstream release notes.
  • Additional topics for Quick Docs, and a better structure. Additional topics because the current set that was mostly migrated from Wiki is almost finished, IIRC there are about 5 topics left to convert; structure because the current navigation is a mess already, we’re lumping everything together in one place and the ToC is huge and makes no sense.
  • Overhauling contributor docs, with a more in-depth focus on Antora workflows and a review of everything else (e.g. joining instructions). I’m not sure if this one is a good candidate for a hackfest though, this might be better solved through the mailing list so we can include everyone in the process, not only people who can make it to the hackfest.

Using i3wm with Fedora
#7

I mean to colloaborate with Petr and the others on a docs hackfest to be held around DevConf to build a model to use to do docs hackfests with targetted groups. Perhaps I don’t understand what you mean by “online user support communities” in this context.


#8

What kind of things would you like to see in place of the change-style release notes we ship now? Do you think they could be beginner-friendly topics?

Would it help to do some strategic thinking and rework the nav structure? Is there anything more required than looking at nav.adoc for this one?

These would be especially helpful for bringing in outsiders to contribute to our docs. It could be a good candidate agenda item for in-person collaboration?

The idea focuses on bridging active participants in user support communities to become Fedora Docs contributors. The benefit is raising the quality of official fedoraproject.org documentation and boost their visibility for those who help others fix problems or figure out new things on Fedora.

To me, online user support communities includes but is not limited to:

In all of these places, every day, people share (and re-share) links to solution pages or blogs on how to solve problems / learn new things. Different communities share different sets of resources. Our goal is to encourage top contributors to these user communities to consider contributing to official documentation based on the additions they want to see. This way, we involve them in the process of creating and maintaining the documentation. Evaluating consistency of frequently-linked URLs across groups is interesting after running a couple of these events.

I was thinking, this could be an equivalent to the QA team’s “Test Days” for specific-targeted goals. Instead, “Doc Days”, for specifically-targeted topics.

Does this better explain?