Fedora Docs community contribution hack-fest with user communities

fedora-documentation
fedora-30

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


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


#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


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


#21

Here’s my wish list:

Number one on my docs wish list is a comprehensive guide to managing a Silverblue workstation. It’s so radically different from any other Linux workstation out there that I find myself doing a lot of mental gear-shifting. Things like:

  1. How do I install Kubernetes? Minikube or something else? OpenShift? Minishift?
  2. How do I build a flatpak from an application source or binary RPM?
  3. Transitioning from docker / docker-compose to podman / buildah / skopeo / Kubernetes
  4. Troubleshooting rpm-ostree

#22

Antora itself is not your typical static site generator, the concept of combining multiple repos is novel and hard to grok. But everyone so far thinks it’s the tool with least friction to combine the docs from different groups. Otherwise so much effort would be wasted just to put it together each time something gets updated.

Ideally you should only know how to write asciidoc, the problem with antora is that it has so many tiny idiosyncrasies that it can get overwhelming. Still I thing the format itself is easier than ReST.
I would suggest that you start with something simple, file an issue and ask.


#23

@ojn @jwf
Sorry for the delayed reply:

  • ( Disclaimer I don’t know the reasons for choosing Antora, and I’m not trying to be a Sphinx fanboy)

A top-level workflow and/or architectural diagram would be good, like the OSBS landing page, showing the steps between the start and finish. Such as the maintainers wiki page, image

Particularly when there is a repo for doc source and another repo for output

Descriptive doc categories would be good. For example in tech docs there are several broadly recognized categories:

  • Instructions (“How do I resize a partition with lvm …?”)
  • References (“What is the syntax for ssh-keygen ?”)
  • Tutorials (“Learn to deploy CI CD using Openshift, Buildah and CRI-O”)
  • Release Notes might be a combination of all three, but they are special in that their publication date is hard to schedule and they might appear in multiple contexts. So, my experience has been that it is best to keep the content of a release note in the source code of the module it describes.
    This allows the note to be written in advance and follow the module through the pipeline.

Usage Metrics to describe the analytics in the docs and also in the Discourse app:

  • Weekly Active Users
  • Broken links: (how many people try to get to a non-existent page? Where did they find the bad link?)
  • Zero-reply threads (how many questions get no response? How old are they?)
  • Feedback collectors (what comments come in from a particular page?)
  • Page views (what pages are rarely read?)

Here are some specific examples of places I ran into difficulty. I’m sure every one was trying to be helpful and I appreciate that they took time to respond.

So, the thing is, nav.adoc doesn’t appear in the repo, so I tried to fix index.adoc , the docs project home page but it appears to be static HTML quoted in adoc! (I lived through 1992 once already, I don’t want to do it again).

multi-repo integration is easy to do with Sphinx, just as readthedocs has done for years

But neither the Python nor the Django projects seem to have this problem; and they don’t require ReST.

IMHO, if adoc is easier to write than ReST, then the solution is to use a tool capable of processing both. It breaks my heart to hear @smooge say that he has to convert old docs from ReST to adoc. We have mountains of content already written in ReST.

OK, I will do that. I recently filed issue #104: Support for creating diagrams from text (eg. Graphviz, diagrams.js, etc.) but I can’t figure out how to tag it as a feature request and it’s not clear where to get help about filing issues.

Well, it doesn’t quite work that way. I was looking to create a PR with changes to the site’s Structure and Nav. These abstractions don’t pertain to Markdown or adoc. Also, adoc and ReST have more abstract expressions like cross-references and directives, which have no counterpart in Markdown.

-Blaise


#24

OK. @ojn, @jwf I did a bit more homework and I have some a suggestions.

According to the Antora.org website, Antora is:

The multi-repository documentation site generator for tech writers who love writing in AsciiDoc.

It’s a new project, focusing exclusively on asciidoc and aimed at developers who are unfamiliar with multi-repo site generators (Typo3 CMS, Drupal, Sphinx, Nikola, Lektor, etc).

  • Deprecate Antora and you will lose zero contributors, you will lose zero content, you will lose zero investment in templating infrastructure.
  • Deprecate Antora and you will save countless hours of converting legacy content just because the new tool is aimed at a single markup language.

You don’t have to use Sphinx, however, the fact is:

  • There is already a group of established projects using Sphinx.
  • Readthedocs invests zero effort recruiting contributions.
  • The readthedocs backendcan be included into fedora infra quite easily.

#25

@ojn @jwf
This response I got from Dan on the Antora team is excellent:

Dan Allen, Antora
To build on what Sarah was saying, we’re not traditionally Node.js developers. We’re actually Java and Ruby developers with almost a decade of experience working on documentation tools. We built Antora for good reason. We felt strongly that there was a void (and yes, that includes Sphinx, which has poor AsciiDoc support). Antora is a new effort to build a documentation site generator around AsciiDoc and Asciidoctor, and to allow content to be sourced from multiple locations by design. We talk about our vision and why we are pursuing it in this blog series. I assure you we understand the needs of documentation teams very well, though we’re still always learning.

blaise
I can see that Antora is an initiative to help tech writers who love to write in asciidoc format. If the human is the source of the content, then it makes perfect sense to build tools to support that effort.

Dan Allen, Antora
That’s correct. I was planning a similar point in my response, but you beat me too it. The goal of Antora is to able to produce documentation sites, particularly large-scale and distributed sites (which now includes Couchbase and MuleSoft). Naturally, we want to meet the objectives that come with that goal. How well we achieve it depends on the success of the open source project. We welcome your participation. Join us in the gitter channel (antora/users) to discuss in real time.

blaise
it’s useful to be able to integrate the compiler output into the content stream.

Dan Allen, Antora
Indeed, there are two primary sources of documentation, human-written prose and machine-generated output (and sometimes a hybrid of the two). Antora was designed to be a modular processing pipeline that can field a diverse collection of content. To get the project off the ground, we configured the pipeline to focus on the human-written prose first (the AsciiDoc documents). But that pipeline can be reconfigured to accept content in other ways (perhaps generated by a script, AsciiDoc or otherwise). As the project matures, those will be supported out of the box too. It’s just going to take time. (Rome wasn’t built in a day, as the saying goes).

blaise
I suppose what I should propose to the Fedora docs team is that we look into having the tools create output in adoc (similar to the way the tools spit out rST)

Dan Allen, Antora
That’s a good compromise in the short term. The other option would be to look into using a custom generator (a script that runs the Antora pipeline, passed via the --generator option).
One piece of advice I’d like to pass on is to encourage folks not to over-apply Antora. Give it a chance to mature. This would be the same advice I’d give for any software. When all you have is a hammer, everything looks like a nail. Be careful not to fall into that trap.