I’m one of the people who are trying hard and putting a lot of work into the revitalization of the docs team and into the improvement of Fedora Docs. And (professionally) writing and publication is an important part of my job.
I followed the discussion, and would like to extract some constructive ideas from it. And some things also need to be corrected or supplemented.
The current docs’ publication process is programmer centric, indeed. But git is just a (small) part of it. The workflow, the tooling (Fedora docs once recommended vim as a writing tool - among others), the limitation of using AsciiDoc, all this together is great for software developers, but simply a pain in the … for at least semi-professional writers or for enthusiasts without programming or writing experience.
If I recap the discussion correctly, this is not a coincidence or an unplanned side effect, but deliberate and intentional. The previous, DocBook based system (i.e. author oriented) was considered too complicated (for programmers and many users). The idea was to make it easier for programmers to write documentation and thereby improve and complete the documentation.
The result, as things stand today, is that (professional) writers are put off (imagine: instead of InDesign now vim), for most users it is not easier, and the programmers, the system relies on, were and are only in the rarest of cases eager documentation writers. They don’t follow through. (The wording is a bit overstated, but hopefully makes the dilemma clear).
But is the git/vim combo really the problem? No.
Remember, the current system is not the first one. Fedora did start with a wiki. At first, everyone was happy, then dissatisfaction grew with various shortcomings.
The solution was a switch to DocBook, SGML and Publican. This gave good results in the beginning. Just look at the documentation for Fedora 20 or earlier. The texts of that time are still almost unchanged, part of the current documentation (Administrator’s Guide). But then it kind of started to fizzle out. Dissatisfaction grew again.
The solution was a switch to the AsciiDoc, git, Antorra combo. It started out great - and now? Surprise, surprise, the same factual issues are back again.
What do we learn from this? Changing the technique again does not necessarily promise success in improving documentation.
The problems to be solved are the same across different technology steps.
But we need solutions other than a change in technology.
Lowering barriers is one of them. But not through other technology, but by designing the existing ones. For example, the “Edit” file button must be highlighted differently. Other information may have to be removed or moved to another place.
We need to better showcase what we have. Has anyone tried to find the docs team on the home page? Who thinks to click on “Learn about the teams focused on Fedora’s outreach …” for that?
We are too few people who care about documentation. So we need an improved onboarding process.
Documentation has no place in the Fedora project and is considered insignificant or superfluous. FESCo considers it superfluous to ensure that we have complete release notes. This is a “nice to have” at best. Many changes are not even described there.
We have lots of highly detailed regulation for building rpm packages, but none of it refers to requirements for the RPM description field.
These are just a few examples. What they have in common: They are changes in the organization of Fedora Project.