This article from LWN regarding Debian picking up some tips from Arch re Docs could be of interest
1 Like
I saw that LWN article and thought it was a great that debian looked to the excelent work that Arch has done for its docs.
I guess you are thinking that Fedora could also look into how Arch gets it’s results?
1 Like
Yea, the docs-team is looking at new ways to get contributors engaged and active.
I dont think we need to invite Arch to conferences etc as Debian did. We can learn some things from Arch and we can copy some things that Debian is doing - if they fit our community.
I note that the amount / number of Arch docs contributors is really high, as is the number of their moderators. Fedora really excells in our forums, Arch in their docs. I wonder if we could empower our community here in the forums to make many micro edits in our docs?
1 Like
There were multiple discussions here on the forums about how to reach higher involvement in Fedora Docs, see links for two of them below.
The git-like approach to documentation together with reporting issues via issue tracker, as Fedora implements it, brings the advantage of a very well curated documentation, but has the obvious downside of much narrower contributor base and quite often outdated how-tos.
The wiki-style documentation as provided by Arch ensures a more agile updating process. Of course it’s not only that, they also have some solid contribution guidelines they have improved over the years.
To be fair though, it’s not fair (no pun intended) to compare Fedora Docs to Arch Wiki. Arch needs a whole lot of configuration in order to obtain a solid, usable system, whereas Fedora tries to provide a good user experience OOTB. Therefore, Arch’s documentation needs to be more comprehensive. Not to be said that we cannot learn from them.
Micro edits go well with Wikis, not so much with pull requests.
To expand the Fedora Docs is a huge undertaking. It’s not strange that it took Arch years to build what they did.
First you need to agree about what type of setup you plan to use. Looking at the Arch wiki I say: don’t go that way. It is complicated, sometimes messy, it contains lots of links to other pages, where you find extra information which you should know before you can continue with the original page.
Not doing that means having the same info multiple times on different pages. Also not perfect when there are changes and you need to find all the places where the text is written.
Writing manuals, or in this case documentation in wiki style, is very difficult. The author has a certain knowledge about the subject and doesn’t always include all this info because: they know it already and therefore it doesn’t need to be written down.
Or, and I count myself as being this type, the author writes way too much, because you may not forget anything, which makes it a jungle where you need to find the correct tree.
What do you write about a subject and what not?
Who will be the typical users of the wiki? What type of Linux users are they? How much info does need to go into the wiki, how detailed?
For beginners? Much data, but written in an easy to understand way.
For intermediates? Can you expect they know the basis or does it need to be included as well as more “sophisticated” info and examples?
For experts? It would have to be a reference work, something they can open and immediately see: oh yeah, that’s it.
Will it be translated so people from all over the world, the typical Fedora users, can read it in their own language?
So before one line is written (or copied) there should be long thoughts and meetings about the who, what, how, where and why of it or it will turn into a disaster. Not trying to be negative here, but that’s just the way it is. It should be examined very well.
Rules have to be made how it will be done.
Example pages have to be made and looked over to see if this is really the way to go.
Subjects have to be gathered.
An order in which they will be processed has to be made (some subjects are more needy than others, one example is the installation of Nvidia drivers, a subject you find a lot here in the forum).
Authors have to found. Not everyone can write about each subject because of not completely understanding it themselves.
A central person (probably central persons) need(s) to oversee it all, give directions, keep an eye on progress, yell (in a friendly way) when a page is not what it is expected to be, etc, etc.
When all lights are green then go for it. But always remember: it won’t be easy, but nobody has said it would be.
I read the links. Comprehensive discussion in the longer one.
My context in Fedora is as a member of Join SIG. We get a lot of people come through that would like to work on docs, and maybe only 10% of them ever make a commit.
Overall, I agree with @pboy that it is not the tooling, but the social environment of Fedora that makes contribution to docs difficult.
The only fix I can think of for this is to have more people with commit rights, and more council and Red Hat commitment to Fedora docs.
Edit: But I did not mean with my top post to rehash previous discussions, rather to take some small learnings from Debian with their engagement with Arch.
I’d say it’s both. While writing new pages might be acceptable with the existing tooling, it’s not appropriate for small edits. I like to help, but I wouldn’t go through the hassle of git cloning etc just to correct a small grammar error or a broken link, maybe an outdated screenshot (which might not be a good idea to be used in the first place).
Then there is the current situation in which different WGs/SIGs are maintaining different areas of the documentation. I understand there are intentions to unify them.
One idea that came up in the other discussion thread was to create an alternate documentation area. Something that Discourse’s Org is doing: on https://meta.discourse.org/ there is an Official Documentation category and there’s a Community Wiki. I don’t know if such an idea would ever have chances of success, but as for the tooling, as mentioned in the other thread, Discourse has a documentation plugin.
It’s nice to see such joint initiatives.
1 Like