Project: Quick Docs Improvement

A rough outline to get us started.

I think, die have three areas of action:

  • Actuality review
  • Qualitiy review
  • Design Improvements
  1. Actuality review

    1. Better visibility of timeliness
      We have the automated last update at the bottom, additionally we need

      • a more visibel marking of which Fedra release the contribution refers to, or which release it is based on
      • the date of the last substantial update or review
      • the author(s) of the last update/review (or the last 3)

      This must be very visible, for example, above the table of contents. This would be an entry to be made manually, in addition to the existing generated entries in the footer.

    2. Probably we can generate a list of the 20 oldest articles, so we can start by creating review ticket for those to find reviewers

  2. Quality review

  • The goal of Quick Docs is to provide how-to’s, but actually we have all sorts of types there.

  • We had a short discussion about classification of content (Classification of all the content on the docs website (Contribute if you can!) - Fedora Discussion) we have a mixture of content types in quick docs.

    • There are a number of articles that do not belong in this category, but are there because the (previous) Fedora documentation was and partly still is too static and monographic (e.g. Administration Guide). Examples of this:

      and many others.

    • Together with the review we should start to categorize each article along the categories mentioned in the thread above and decide to relocate it.

  • At the same time, we should develop an author guide for Quickdoc.

  1. Design Improvements

@aday started a thread about docs design. His ideas and concept. I think his ideas and concept are particularly suitable for Quick Docs. We should find out how we can start with it.


I was thinking of creating five tickets for these:

  1. Add timeline /author information to each article
  2. Generate a list of the oldest articles for technical review
  3. Categorize Quick Docs articles into how-tos, tutorials etc.
  4. Write an author guide for Quick Docs
  5. Docs design improvement /relocation of Quick Docs articles

What repo should these tickets live in? Should they be ordered by priority?

1 Like

Would something like this suit your needs?

How it’s done?
You can add revision metadata just below the authors line:

= Fedora Documentation Team
Ben Cotton; Peter Boy; Petr Bokoc
2.0, 2022-11-26: a new beginning


= Fedora Documentation Team
Ben Cotton; Peter Boy; Petr Bokoc
:revnumber: F37
:revdate: 2022-11-25
:revremark: a new beginning

All fields are optional.
More details in asciidoc documentation.

I think that meets very good what we need and what is asked for.

Maybe, we should make it part of a documentation guide.

Is it already usable? Can I use it with our server documentation?

You can start using it for any documentation, but it needs an update to the UI to actually show up.
I plan to push that part on staging first, among other things, in the next few days.

1 Like

Can things like author list and last modification time be autogenerated from Git where the info already exists? Otherwise this is another thing to do manually and it’s all is likely end up as more thing that are outdated when folks forget to update them.

For revnumber: I assume we can have multiple revs there because lots of information on things like quick-docs are not specific to one Fedora release.

The revision informations, in this case, are more aimed to give data about the last review of that document.
This is different from when this document was last updated (which is still available in the footer).

I think the revnumber should be the last Fedora version used to review this document.
If I see a document saying it has been last reviewed for F26, I quickly understand it’s most likely obsolete content. But If I see F37 here, I can trust the content. In such a scenario, I’m not sure how relevant is to know that this doc is also valid for previous versions of Fedora.
I believe our docs should only focus on currently supported versions. And if something changes between two supported versions, that should be mentioned in the document where it’s needed.
Does that make sense?

1 Like

I get the idea, but the image of how it’s shown doesn’t really tell me “this was last reviewed for F37” or that “this applies to F37”. To a naive user, it could just mean “the current release is F37” or anything on those lines. We can never tell how users interpret what we write—but they almost always find ways that we’d not thought of.

Should we tweak this to be very explicit: “last reviewed for F37 on ” if that’s the idea?

I also don’t know if the author/reviewer names are useful to readers—we dont want users using this information to privately contact authors about pages. It being in the metadata is fine—that way we know who last reviewed it and it is unlikely that end users will look at the sources—but does it add value to have them listed on the html version that folks see (and that’ll get crawled by search bots etc.)? What’s the idea behind this? Sorry if this has been discussed somewhere, please feel free to point me to the the discussion. I’ve not been able to keep up with all the improvements :slight_smile:

If we do want author/reviewer names in there, maybe we say: “last reviewed for F37 on by ”?

Regarding the author names: This information was already there at the bottom of the pages. I believe this is a nice way to credit docs writers. This is also completely optional. Not all pages have this information currently, that is up to the writer to put their name here if they want to. This is also one of the many reasons it’s not automatically generated.

1 Like

That’s true, indeed. On the other hand, it should be short. Maybe we can count on a user coming up with the right meaning in the course of using the documentation?

If I remember correctly, the idea came up years ago by Matthew. Providing credit is the only currency an OSS project has. It was discussed in one of the issues at. Issues - fedora-docs/docs-fp-o - Unfortunately I couldn’t find it in a reasonable time. And the other idea was to make Fedora Docs more touchable and more concretely visible, as well as to emphasize that the docs are not just there, but a shared commitment of the community (and thus perhaps to encourage participation).

1 Like

Fedora User Docs has the similar structure and content as Quick Docs such as; network, upgrade, storage, SELinux, customization. Quick Docs has to be unique in resource type and what it solves.

I think categorization makes sense as a first step to review. Then we can see what needs rewriting, new pages/categories and which pages could be retired and reorganized. + what is overlapping with Fedora User Docs.

I’m not sure what you exactly mean by “Fedora User Docs”.

Nevertheless, @aday suggested an extensive redesign, which seems to be specifically useful for Quick Doc. He suggested among others to drop the navigation column and replace it by categories. The problem is to develop a systematic categorization. Maybe we should do it recursively step-by-step. I would suggest to start with

  1. Related Edition/Spin
    Workstation, Server,Coreos,…
  2. Type of docs
    How-to, Tutorial, Guide

Question is: Do we have a technology in place to include and display a categorization? Probably something like the authors? And do we have the technology in place to filter by categorie?

Regardless of categorization, I suggest starting with content revision. Thanks to @anthonymcglone we have 2 nice lists of old Quick Docs articles in pagure.

I suggest we work in chunk of 5 articles and start with the first list (articles with a disclaimer). That means, we create an issue for each of the first 5 articles and work on the content. As a side step, we include the author/revision/revision date specification at the top.

The problem is to develop a systematic categorization. Maybe we should do it recursively step-by-step.

Fair enough.

Regardless of categorization, I suggest starting with content revision. Thanks to @anthonymcglone we have 2 nice lists of old Quick Docs articles in pagure.

Sorry, I missed this update. Sounds like a plan.

I have been made aware of a suggestion about the Quick Docs on ask.fp:

Jeff made me think in terms of something like the 7-steps guide for pagure. Since the Quick Docs have not yet been migrated to gitlab, it might be thought if it makes sense to create such a guide for pagure just like we have it already for GitLab.

Obviously, such a decision should be linked to the question if and when the Quick Docs will be migrated to GitLab.

But at the moment, the absence of a “HowTo contribute on pagure” can maybe hinder here and there some contributions. (Maybe some parts of the Gitlab-HowTo can be re-used to safe time).

Unfortunately, I cannot support much. I have hardly time at the moment to even check what is going on around Fedora (so, if you have already discussed this somewhere, ignore this post :wink: ).

I’ve been working on a way to categorize pages with Antora, and I think I’ve found something we can build on.
There is no UI for it yet, but this is how it looks for now (this is not the final design):

This page is automatically generated at build time.

There are 2 ways available to categorize content here:

  • Categories: Each article can belong to one category.
  • Tags: Each article can have one or more tags associated with it.

We can implement one or the other (or both) and we can also use tags as categories.

While the UI is far from ready yet, you can still start using the following attributes in your articles:

= Page Title
:category: firewall
:tags: firewalld, security

What do you think?


Both ways appear to be intuitive solutions to organize docs.

I think, that for pagure edit is useful anyway. It’s not only Quick Docs that currently uses pagure, but also a lot of other docs, e.g. the new Workstation Docs.

That’s great! I have a slight preference for tags, because it is more flexible. But it we could implement both, the :category: could replace the navigation menu items, as suggested by @aday.

1 Like