Goals for documentation content in the next 3 months?

At Issues - fedora-docs/docs-fp-o - Pagure.io, we have 40 potential goals we can choose from.

Additionally, @mattdm made a call for removal of old docs, which resulted in some activity. rsp. activity announcements.

  • @darknao (re-)started the idea of a banner at the top of outdated doc pages (#116, #118). How far have we come there?

  • @ryanlerch started to work on #183 Step 1. How far have we come there?

  • @darknao and @abitrolly commented on #67 and, if I remember correctly, there is some progress. What is the exact status today?

What do you think are the 3 most important content improvement goals we should additionally try to achieve? Either of the list of issues mentioned above, or completely new ones?

1 Like

I don’t think it’s 40. From my perspective, the use of pagure issues and discourse threads seems a bit arbitrary and thus, inconsistent/redundant.

I suggest to close issues like #186, #187, #16 and consolidate that on the Discourse thread, which already exists?

If tasks/content-adjustments rise out the discussion, these could become pagure issues about how+when+who to do/implement/adjust, and about solving problems around implementing/adjusting. The discussion about whether there have to be changes and what type of changes to achieve which goals/advantages (which are more strategic questions) seems to relate to discourse. This is how I used to do it; just a suggestion!! :wink:

Personally, I have a deep desire to see Fedora Docs make the migration to GitLab and better centralize our repositories there. This is my #1 desire.

My second top desire is to see improved continuous integration and staging for Fedora Docs. I wish it were not so hard to verify whether changes are “good” and working before a Pull Request is either merged or tested by an experienced Antora contributor. Getting things like preview links for all PRs made to all Fedora Docs repos would be a MASSIVE win. But if we use something like Pagure, this comes with a huge maintenance burden since we have to roll our own CI system and someone has to maintain it, presumably as a volunteer. GitLab could also simplify this by using its powerful CI system that would not require someone else to host and manage.

Unfortunately, I have little capacity to lead on this work because my personal situation has changed since the pandemic began. Maybe one day I can be as active as I was before, but for now, I am mostly part of the peanut gallery with the historical knowledge I have about Fedora Docs.

3 Likes

My “ceterum censeo” on this: No CI workflow, no matter how beautiful and technically elegant, can improve the quality of Fedora user documentation even one iota. With the current rate of change so low, we could keep the “old cart rattling down the road” for a long time to come.

I am quite involved right now in creating documentation for Fedora Server Edition. The pagure repo with the limited available administration capabilities is no obstacle for this. An obstacle is the limitation of expression and layout options conceptually caused by the adoc format as well as the relatively stiff git PR workflow, which has already deterred and “driven away” some authors, who were not software developers. And the very biggest obstacle is the lack of authors.

This might be something that requires more than 3 months time, depending on bandwidth and whatnot, but I would like to see/help with implementing a search feature. It’s a common user behavior and it can help the docs site in situations where taxonomy falls short. I’m continuing looking into the antora-lunr extension for this.

3 Likes

CentOS side, it looks like the “Enterprise Docs” are being made available here:

The Contributor’s Guide is currently on GitHub here:

@shaunm Is this something that should be migrated to the seemingly empty (to non-members) CentOS GitLab org or left as-is?

1 Like

Because we have already a long to do list, it is maybe worth to think of embedding an external search function. Duckduckgo or such, something like on, e.g., https://www.schneier.com/ . Less to implement and to maintain.

What does the “This” refer to? The original idea is to determine from the many possible or desirable improvements a list of what we want to achieve in 3 months (and then hopefully can).

That is not about content, but about usage or functionality.

I am strictly opposed to such an “outsourcing”. This would bring all sorts of privacy problems and force Fedora users to give their own data to commercial trackers for use or deal with search engine configuration and all sorts of commercial subterfuge, dubious tricks to circumvent or hide abuse. This would be another dismantling of Fedora’s principle of freedom. And it would lower the quality of search results and infuse them with commercial advertising or other commercial interests. See the cited example schneier.com.

If Fedora is incapable of setting up and maintaining a search engine such as Solr or Elasticsearch, we should drop it altogether and instead optimize SEO and let every user use the search engine they trust (and may already have configured for their everyday usage, including monitoring).

It’s bad enough that Fedora no longer has the power to run a repository meeting its demands by itself and in freedom.

I doubt that this is linked to duckduckgo, but it was just an example to avoid even more that has to be maintained. However, of course, the question of how far such an approach can fulfill the compliance requirements of Fedora remains open. Btw, a traceroute to docs.fedoraproject.org also ends up at AWS ; )

I could agree on that approach :slight_smile: At least we can agree that something has to be done, may it be SEO or a search function.

This is already discussed on Discussing Fedora Docs website improvement

1 Like

“This” just meaning my suggestion of prioritizing a search feature, sorry if I wasn’t clear.

A search feature is present in the list of potential goals that you posted. Is there anything else in that list which is about usage or functionality, and not content? Those could be prioritized separately.

Sorry if my post came across as a rejection. I am very much in favor of introducing a search function, implemented in free software and not delegated to a commercial service provider.

The objection of my previous post was (and is) to keep the thread focused on content, i.e. writing new or updating existing articles.

There’s a proposal on centos-devel on how to organize projects under the CentOS org in GitLab.

https://lists.centos.org/pipermail/centos-devel/2022-February/120216.html

I do think we should move the contributors guide (and anything else) to GitLab. But we might need to formalize the docs team as a SIG to secure space there.

The enterprise-docs repo, however, will probably stay under the redhat/centos-stream project. It’s a bit confusing, but at least they’d all be on the same hosting site.

I guess this means that even in CentOS there will be doc areas open to non-Red Hat employees after all (as recently discussed as a possible obstacle)?

Regardless of the resulting organizational issues that now need to be resolved, in the next step we should try to determine, which subject areas this open space should or can address. This should then determine which topics/articles we can work on together for CentOS and Fedora. We should probably start a dedicated thread about that. I don’t know how far in progress the CentOS conversion is. When would it make sense to start a separate thread?