Fedora Docs community contribution hack-fest with user communities

[blaise (Blaise R Pabon)]

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

@jwf

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

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.

@jwf

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?

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

@ojn

Antora itself is not your typical static site generator, the concept of combining multiple repos is novel and hard to grok.

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

@ojn

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.

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

@ojn

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.

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.

@ojn

I would suggest that you start with something simple, file an issue and ask.

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.

@znmeb

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.

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