#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?

5 Likes
Profileration of community communication channels
Profileration of community communication channels
Secret plans revealed: what CommOps hopes to accomplish in Fedora 30 release cycle
[2018-10-31] [Minutes] Appreciation Week prep, F29 => F30 triage, goodbye mailing list
Secret plans revealed: what CommOps hopes to accomplish in Fedora 30 release cycle
#2

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

1 Like
#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?

#9

FIW, I submitted a proposal for DevConf.cz for a ‘Fedora Docs Hackathon’ (even though I read this thread before, it didn’t come to mind when I was submitting the proposal). If it gets selected for the event, we could perhaps use it not only to hack on docs but also to plan other future activities.

(I at least remembered to invite @pbokoc to be a co-organizer for the DevConf.cz proposal.)

4 Likes
#10

Awesome, this is good to hear. If I am able to attend DevConf.cz this year, I hope I can be a part of it. We can revisit once January rolls closer.

#11

I think the idea is awesome.

What I would suggest is that we make how-to pages:

how to contribute to docs
how to do video editing on Fedora etc

Some of those topics would go under Quick Docs and others would be more general or special topic based.

The thing is, to attract the new contributors it needs to be as painless as possible to start. So if we set up submission form on the main fedora website for how-to guides we can get some drive by contributors from Ask-Fedora, reddits, blogs etc. It would still be a lot of work to validate, but I think what we could do is that whenever someone encounters a good blog post worthy for official docs how-to pages we just email the person and ask them if they are willing to re-licence their blog post under CC-BY-SA and submit the solution to the web form to possibly be included in the official docs. This could encourage more people to become continuous members as they see that their effort is appreciated.

1 Like
#12

I just posted a suggestion to the thread about fixing the structure of the docs site; and I said to myself it would be best to submit a PR so they can see what I’m talking about

So I (re)join the docs list (now using a better email address), read through the contributor’s guide and start looking at the source.
But…
The homepage file doesn’t look like asciidoc to me:
https://pagure.io/fedora-docs/docs-fp-o/blob/master/f/pages/homepage/modules/ROOT/pages/index.adoc

it looks like html output instead.
Perhaps there is a permissions problem with my FAS account (blaise) ?
If someone points me to the source code, I am happy to take a few swipes at organizing it.
Are there any fedora sites using a layout that we want to clone?

#13

It is technically AsciiDoc, just with inline HTML (denoted by the ++++).

#14

Well, OK, I guess what I was hoping to find was the text without all the formatting.
If that is, in fact, the real source doc; then I will go ahead and see what I can do.

#15

FWIW, readthedocs doesn’t seem to have any problems getting people to contribute docs. They make it super easy. Has this group considered a similar approach?
(ie. an abstraction layer that hosts docs as individual artifacts, rather than a single monolithic artifact)
RTD happen to use Django and Sphinx to compile the docs. There is already an extension to acommodate those who prefer to write in asciidoc.

In fact, the Django project started as a solution to automating online journalism.
Unsurprisingly, they have a nice guide to writing documentation

#16

Ok. I’m sorry to say I have to concede defeat and withdraw. I thought that I could figure this out because I was familiar with readthedocs, Sphinx, Mkdocs, and Nikola. I didn’t expect to have so much trouble understanding Antora. Good luck.

#17

You can probably write in your tool of choice (markdown, restructured text, etc.) and convert to and from whatever markup Fedora is using via Pandoc.

On the appropriate use of Antora
#18

I just found an old issue in an unused repo where a contributor had a list of good to have topics for the Sysadmin Guide. Some of them seem like they could be a decent first assignment for a new contributor. Here’s the list:

  • Filesystem Information (e.g. ACL’s, permissions)
  • SELinux details (security contexts etc)
  • Common Networking tasks (firewalld, networkmanager, ip command, ss command, etc)
  • Disk Management information (LVM’s, parted, etc)
  • Securing a Fedora host
  • Creating and Managing Virtual machines and containers
  • Using and securing flatpaks
  • fundamentals of shell scripting

https://pagure.io/fedora-docs/system-administrators-guide/issue/24

1 Like
#19

Sorry, I guess I forgot to reply.

Release Notes need an overhaul.

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?

The problem with Changes is that they’re already on the Wiki, so all we’re doing is basically duplicating them. It’s nice to have them in one spot, but I’ve been thinking we could:

  1. Involve SIGs more - have them write about what changed in their SIG for the release
  2. Put together a list of important areas - not necessarily packages - that we’d like to cover in every release. For example, every new Fedora release comes with a newer Firefox version, and since that’s the default web browser, it’s important to a lot of desktop users, so in each relnotes we’d say “The default browser in Fedora X is Firefox Y, changes include Z, see upstream release notes at for more details”. We’d need a list of components like that, though, and we’d need to include all the major areas of interest (desktop, development, containers, etc. etc.).

I’ve been doing 2) with the installer for ages - I always ping the anaconda team and ask them to give me a high-level list of changes, and I write it up for each release. Ideally we’d do something like this every release and for a whole bunch of components, but we need a list of those first. It’s also going to be a ton of effort to do every time…

Additional topics for Quick Docs, and a better structure.

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?

A lot of the stuff in quick-docs seems like it should be moved to the Sysadmin Guide, so it could be useful to look at that as well, but yeah, generally this shouldn’t require much more than that - just sitting down and thinking how to make that mess easier to navigate.

#20

@blaise If you have time, could you list some of the specific things you hit that made contributing feel difficult or challenging? Knowing what was frustrating to you is helpful, because odds are you are not the only one. CommOps is specifically created with trying to make things like this easier for folks peeking in for the first time.

Knowing your pain points will also help us make a plan forward to solving some of the pain points. I think @asamalik and @bex would also find this interesting too.

Super! Thanks @pbokoc. This list of topics is helpful. I hadn’t thought about the Sysadmin Guide for this virtual event, but I think it’s definitely relevant.

Perhaps this is a necessary pre-requisite task before we run a public docs-athon event.

1 Like