Docs meeting agenda: 2022-08-31

Here’s the agenda for the meeting 2022-08-31T18:30:00Z in #fedora-meeting-1

If some time is left at the end, I have marked the two remaining issues for the meeting: One is 9 months old and the other 6 months. We should just clarify if we put these issues on hold, assign them, close them, or proceed otherwise. Should be done in 2 or 3 minutes.

There is not much to read in both, and both relate to Fedora Accounts Docs:

I will be very late today if I can even make it. But concerning the major topic of today, I would like to add one suggestion you can discuss if you want:

When people end up at a Fedora release Docs that is no longer supported, they will get the following warning on the top of the page:

E.g., here at F32 Docs

Complementary, I saw yesterday that pbokoc added the line include::{partialsdir}/unreviewed-message.adoc[] to several Quick Docs to indicate that they need review (he explained it in the readme).

Why do we not combine both?

Add an information to each page file that stores the last review (+revision if necessary) time/date (e.g., release-focused: reviewed(+revision) during F36). Commits don’t indicate much as they are often just formatting.

As soon as a page has no longer a review(+revision) at the current release, add a warning to the top of the page (like that above) to the reader: something like “warning, the last review of this page has happened at F34”. Then, the readers have the information and can indicate themselves if this is sufficient up to date or not. If contributors made a review/revision, they can then change the review/revision-release number in the respective adoc.

One major issue is that readers do not know what they are up against. Even if they are on a page that is still up to date, they cannot know, so they do not trust any page and stop to link/distribute it. The Docs have no value for them. All obsolete Docs contribute to the reputation of and trust in Docs.

With this approach, we can keep all our Docs, but the readers would be in a position where they know what they are up against. And this can be a foundation on which trust can rise. Trust + some valuable content might increase readership, and increased readership might bring authors+maintainers.

→ Authors come when they trust and use Docs. If they don’t do both, why should they come to author? Or why should they expect others to use/trust?

I had the idea when I was discussing with @pboy yesterday and after the use of a very old Quick Docs page in Ask.FP.


Something else what we have to overcome: mini-contributions → single sections are updated but nothing more, and updates don’t get aligned to the remaining. The outcome: the install guide jumps between many different releases and editions (as an example, this is why the Install Guide wants to create user accounts twice).

Hope that makes sense.

We discussed that already some months ago, but didn’t follow through, much to my chagrin.

And may I remind mattdm’s statement: Reputation is the currency in open source. So, we should add authors information in the same go.

We do that in the Server documentation, if you want to get an impression - although we do it quite primitive and rough for lack of knowledge of better options.

1 Like

I meant information such as the include::{partialsdir}/unreviewed-message.adoc[] in Quick Docs. So, e.g., a comment that contains “//reviewRevision=F36”. It is in the adoc file but not visible to the reader in the final output. However, based upon this information, the system can determine if a clear warning such as “Warning - this page was not reviewed/revised since F26” (see the warning image above) has to be shown to the reader or not.

However, your approach of additionally adding author information to the output page might decrease the problem of the “unthoughtful mini contributions” I mentioned above, at least if it is clear to authors that the expectation is higher than just putting something in the middle without considering the above and below, or if someone checks commits in advance for alignment. Nevertheless, you are talking here about maintainer, don’t you? I mean, if one is mentioned author, and another one wants to contribute, the responsible maintainer (=mentioned author) remains the same, or did you mean something else? So determine someone who is responsible for a page (which does of course not mean that no one else is allowed to contribute)?

I see the advantages of your approach, but still, I think it should be a maintainer or so, and not an author, which would imply dedicating the “authorship” to one person.

A general thing which me might consider later, when we get deeper into details, is to describe what “review+revision” contains (such as including checking the alignment).

However, the automated warning based upon information in the adoc file (invisible to readers) would be my first goal because we can achieve it with the resources we have, and it can achieve a trust-foundation. It might be complemented by an automated second sentence in the warning if a page has no maintainer (based upon your approach; or whatever we call it): e.g.,

//lastReviewRevision=F26
//maintainer=None

leads to
“Warning - this page was not reviewed/revised since F26. Currently, it has no maintainer” or such within an image like that
https://redhat.discourse-cdn.com/fedoraproject/uploads/default/original/2X/8/83ef6b3485c27de4250273a18c430740ca7894ee.png

Minutes and full logs are available.

Highlights

  • We discussed the improvements in this thread and decided to focus our efforts in the short term on rolling out the new Docs format, with a goal of having it ready for the F37 release.
  • For next week: discuss improving the Release Notes process/attention
  • @darknao will chair next week’s meeting

Action

  • @pboy (and perhaps @likeanushka) to develop a step-by-step plan for the re-formed product-oriented docs
1 Like