Fedora Docs community contribution hack-fest with user communities

fedora-documentation
fedora-30

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