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.
Probably we can generate a list of the 20 oldest articles, so we can start by creating review ticket for those to find reviewers
Quality review
The goal of Quick Docs is to provide how-to’s, but actually we have all sorts of types there.
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:
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.
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.
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.
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?
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
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.
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 - Pagure.io 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).
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
Related Edition/Spin
Workstation, Server,Coreos,…
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.
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 ).
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):
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.
).