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

2 Likes

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

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

alternatively:

= 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