This is a point of discussion that came up early on in our last revitalization attempt in 2022. To put it bluntly, Docs was “hijacked” by the programmer faction when it first fell dormant after Fedora was founded, and a programmer workflow was imposed on it, and then it became boring and the “programmers” disappeared from Docs. If I understand correctly, none of those who switched Docs to AscciDoc and Git workflow about 5 years ago are still active in Docs. And now we have a workflow that makes it easy for “programmers” to contribute. But traditionally, ‘programmers’ are not exactly avid “documenters”, and nor in Fedora.
However, the combination of Antora, AsciiDoc, and Git is not entirely unsuitable, especially for technical documentation. It offers simplifications for many text elements in typical documentation, such as predefined templates and tags. At the same time, it lacks many features, especially collaboration and discussion. What every authoring program – InDesign, Word, LibreOffice – offers is missing. And due to the specific AsciiDoc format, many tools cannot be used.
Incidentally, the same problem between “programmers” and “documenters” applies to the hasty switch to GitLab. After the switch was completed, everyone who had previously been involved in the transition suddenly disappeared. And the whole system still doesn’t work properly today. Many who contributed to Docs back in the pagure days have given up.
Anyway, we’re convinced that it doesn’t make sense to switch to another system now. Instead, we need to make the most of the current options — in other words, hide the “programmer” workflow behind a “documenter” front end.
In the first step, the “front end” will be fairly primitive and consist of a collection of small tools and a step-by-step description. Fortunately, @jednorozec has agreed to cooperate with Docs regarding Forgejo, our new repository süpace, and to drive forward the development of Docs-specific tools. This allows us to create a solid and customized basis for a key element of our workflow that is missing in GitLab.
Fortunately, this kind of drastic change is relatively rare. Otherwise, we would truly be lost. But good documentation is essential, especially during such a transition. However, our change process treats documentation as a “nice to have” rather than a requirement. Fedora needs to improve here.
Fedora Docs is in general about user docs, contributor docs, and developer docs. The initiative focuses in terms of content specifically on user documentation. And prior knowledge varies. Getting started does not require any special prior knowledge. Other things require at least minimal user experience. It may be useful to include this point in the metadata.
Hm, you know, we are Fedora. We are “innovative”, the “leading Linux Desktop”, look at our project homepage. Do we want to copy something?
Seriously, the initiative is based on a long ongoing discussion, started about 2021, about technical documentation, volunteer work, and extensive experience with Fedora-specific structures and culture. We are not reinventing the wheel, but we are not copying anything either. Naturally, we are incorporating existing discussions and findings on documentation. The initiative is an action-oriented, Fedora specific compilation and adaptation of these elements.
It would be very helpful if you could push forward with the translation in the Docs Team. So far, we have been fully occupied with other things.
Nor you need with Fedora and Asciidocs. I myself use AsciidocsFX, for example. It allows you to work in a similar way to standard word processing software.
And yes, we need to improve the usage, and yes, we have to add GUI tools, too.
The plan is, to include all Edition-agnostic topics in Quick Docs, either keeping this name or find a better one. And the Docs home page focuses on the Editions. But regardless of that, we need to adapt the landing page to current developments. The page was created three years ago.
Agreed, but at present we simply do not have enough resources. A few years ago, we started to publish a list of the 10 oldest documents each month and initiate an update discussion. But even for that, there were not enough resources. But we need to establish something along these lines—and automate it in Forgejo if possible.
I can’t go into all the items right now. I would like to include them for one of the initiative’s first meetings about composing a detailed work plan.