Not using git for docs

Not using git to manage documentation would be a great start. There is another post around here that discusses this but using git for documentation is a programmer-centric plan. However, many of the people who would write and contribute to documentation don’t understand git, patches or PRs/MRs. By the time someone climbs that hill, their motivation to contribute has declined. Getting a small contribution from a large number of people is just as important as having a few heavy contributors.

I think we should consider what works in other places. I would say three of the most comprehensive and well updated sources of Linux documentation are the Arch Wiki, the Gentoo Wiki and the Debian Wiki. All of those sources do just that. Anyone can create an account and start contributing.

Perhaps there are different types of documentation and a different process is needed for things like a formal manual.

With the velocity that things change on Fedora, having up-to-date documentation is probably more important than having perfected, reviewed and approved documentation

2 Likes

I understand that git is seen as programmer-centric but do we have alternatives? Every tool will require some training—and the use of git with modern front-ends (GitLab) makes the task of reviewing and tracking changes very very easy. It is certainly better than the traditional e-mailing back and forth of doc files with track-changes etc.

I’ve also noted this on other posts—one does not need to use git on the command line to contribute to docs—pagure/github/gitlab all allow editing files in the browser and opening a review request right from there. (maybe using “review requests” instead of “merge” or “pull” requests could be a first step in removing git centric jargon). One does not need to know what a patch is or a commit or how to bisect. What people need to know is: click here, modify, submit for review. What happens under the hood is irrelevant.

For example:

https://ask.fedoraproject.org/t/sporadic-ask-fp-contributions-to-fedora-docs/24324/6?u=ankursinha

3 Likes

In short, I think this will practically not be possible. But I will create a thread focusing the topic of making Docs more attractive, more easy for potential contributors and decrease entry barriers - based upon our “case study” in ask.fp: Git is at the center of the issues but not its replacement. As Ankur said, I think GitLab helps us to make things much easier. On one hand, we have to get over some (increasingly false) assumptions about git, but on the other hand, we have to more focus the perspective of potential contributors as you already indicated. Maybe we can focus that topic then in the other thread (give me some time to sum up the incentives from the recent days). I think the recent ask.fp <-> Docs case is a good case to start a discussion on.

I think this will not work as it links to the lounge :slight_smile:

Yes. I linked three of the most common comprehensive Linux documentation sources above and none of them use git.

They make it easy if you understand how source control works in the first place.

I think that as open source contributors, we have lost track of what a complicated and burdensome process that is for most people. Yes, using the web UI might be easier than the command line but it still isn’t intuitive or obvious for someone who is a writer.

For illustrative purposes, let’s walk through the contribution process for the one of the sources I mentioned above.

  1. You are looking at a page of documentation and realize there is an error or more information you could add
  2. You see that it has a login/edit button at the top of the page
  3. You are a new contributor so you click the login button and are prompted to create an account.
  4. You modify the content, click the preview button to review it and click “save”
  5. Your changes are now available to the world and you get an immediate sense of reward and are encouraged to add more in the future

Now lets walk through the process using pagure/gitlab/github.

  1. You are looking at a page of documentation and realize there is an error or more information you could add
  2. There is a message at the very bottom of the page that reads “Learn how to contribute to Fedora Docs” so you click on it
  3. You then have to review 5 pages of documentation that describe the relatively complicated process
  4. You are committed enough to contributing so you start going through those steps one at a time starting with creating an account
  5. You now have to somehow navigate to the repo which contains the document you want to change
  6. You have found the correct repo and are now staring at file structure, you now have to figure out which file needs to be changed
  7. You find the file that needs to be changed
  8. You are now met with a representation of the file and a bunch of buttons referring to branches, history, raw views and because you read the documentation, you know you need to click “Fork and Edit”
  9. You make your edits and save/commit them. You hope they are correct because the process to fully preview them is more complicated than you are capable of following
  10. Now you need to create a PR/MR describing the changes with a whole bunch of complicated buttons and terminology
  11. Your changes are now waiting someone to review them
  12. You then need to get consensus from one or more people about the changes which may require discussion and revision
  13. Eventually, your changes are published

You probably lose 90% of your potential contributors at steps 2-3. Many more will lose interest before getting to the end of the process. Many of the people who do get to the end will consider if it is worth it contribute in the future.

I can’t think of a single Linux distro that has documentation managed this way that is successful at having a comprehensive documentation library that is kept updated unless they are using paid resources to do it.

All of the successful documentation sources I am aware of follow the first process.

3 Likes

I must be low on coffee but I can’t find these…

No, that’s the misconception—one doesn’t need to know anything about source control. As far as we are concerned, one is making a change and submitting it for review. When it is reviewed, it gets merged.

But this is why we dropped the wiki! There’s no peer-review, and that’s very important for a well maintained documentation :slight_smile:

No, that’s not the next step. The next step is to click on one of the icons in the top right corner to go directly to the source of the document.

Again, this is not required. The “steps to contribute” should/will have a page that says “just use gitlab in your browser like this…”

Again, if one clicks on the icon in the top right, these steps are not required.

The buttons are an issue. I don’t think we can modify “fork and edit” to “create a copy and edit” on a Gitlab instance that we don’t host ourselves. We could perhaps file an RFE for this upstream.

A live preview is an issue. I don’t know if there’s a way around this. We could look into making the build.sh && preview.sh steps easier or online somehow, but we’ll need to think about how this can be done. I may be imagining this, but I think Gitlab supports asciidoc syntax highlighting and so on, not sure about a live preview the way github does for markdown.

(In a lot of cases, unless I’m adding new sections and reformatting pages etc., I don’t tend to really check the preview after each change)

In my book, these three steps are mandatory. We can go back to “anyone can change anything” but then we’re not writing verified technical documentation, we’re writing another wiki—which is no different from any one’s personal blog because no one else has reviewed the content.

I think most people refer to the Arch docs, and they do also have a process in place:

https://wiki.archlinux.org/title/ArchWiki:Contributing

They do need maintainers to keep an eye on things. I have no idea where/how the peer-review process happens, though. Note that this is also why we do not and can not cite Wikipedia or other such sources in our scientific work—it is not peer reviewed and so cannot be assumed to be true.

3 Likes

I suggest to first tackle the other thread because the other is less abstract and might be a better point to start a discussion about increasing contribution because it already puts forward a “practical example/experience”:

But of course feel free to challenge my derivations!

1 Like

Well…the topic got split so they are in the other topic now. :smile:

That being said, lets keep it simple. In my opinion, the most accurate and comprehensive source of Linux documentation is the Arch Wiki. It is entirely maintained by volunteers and has almost no barrier to entry.

I strongly disagree with this. This is what you get when you click the edit button:

A non-technical person who has never used a source control system will immediately be overwhelmed at this point.

The problem is that if you don’t read those 5 pages of instructions first you will have no idea what to do if you click the edit button as described above.

It is still exceptionally hard to navigate because of the way the document references work.

Peer review doesn’t have to happen prior to posting. It can happen afterwards. There are many, many successful examples of this.

This is just my opinion but one of the big issues with the Fedora wiki was that it was a supplement to the documentation instead of the source of the documentation. As a result, it lacked critical mass.

2 Likes

But what is source control specific here? Wouldn’t one click on the “open …” button instinctively?

If you can be more specific, this can be improved. The links take one directly to the source page from what I know—there’s no further navigation required.

Could you share these examples please?

In normal practice, where would one do a “post-publication review”? In my anecdotal experience, “post-publication review” in documentation only occurs when there’s such a large issue that it creates a little bit of an outrage, and then people run around trying to fix things—it’s a reactive system. Until someone finds the error and reports it, the wrong information lives on.

This isn’t quite the case. All documentation apart from the release notes were on the wiki for a long long time. It just didn’t work for a number of reasons, which have been discussed before in various threads.

2 Likes

I think many people would be overwhelmed. Decide it is too complicated and quit.

Not that link. The way the pages are linked together. For example, if you want to make edits that span pages there is no seemless way to do that. It is a side effect of using git and asciidoc together. I don’t think there is much that could be done about it.

The Arch wiki.

My only criticism about your suggestion is a fair comparison must be made against user documentation sites run by Antora or equivalent static documentation website framework (Hugo, Jekyll), rather than wiki.

Edited: git-based workflow is one of pre-requisites for contributors in Docs team. I took the challenge and trust it is worthwhile to getting the hang of the git.

1 Like

So, is the argument here, “People can’t learn things”? Or, “asking people to learn things they don’t already know is an unreasonable expectation for contributors to documentation on a technical project”?

I’m honestly not clear on what the goal is here, but the impression I’m getting is, “We want the project documentation to be WYSIWYG-editable by anyone who’s ever seen Microsoft Word.” Accurate? Because, if that is the proposed expectation, please allow me to register my vigorous dissent.

2 Likes

At the risk of being indelicate or unwelcoming, the crux of that dissent: A commonly-taken position in these discussions is that, whenever any sort of barrier to contribution is detected on a project, that barrier is obviously and implicitly detrimental and must therefore be stormed (to strain a metaphor or three).

But, for a prospective documentation contributor on a Linux distribution, if the very concept of source control is too scary and overwhelming to them, are they really prepared to contribute accurate and sufficiently technical documentation that meets the quality standards of the project?

The Wikipedia community has codified this notion into one of the project’s many pithy internal catchphrases: Competence is required. In other words, in order to contribute to Wikipedia, you need to be able to learn, understand, and apply the basic policies, standards, and guidelines of the encyclopedia, including basic use of the editing tools and conformance to the project’s Manual Of Style. If you can’t do that, merely wanting to contribute is not sufficient reason for the project to accept your contributions.

(And this is Wikipedia, where many contributions require no particular technical skill or knowledge whatsoever. Whereas, when it comes to Fedora Docs, I would argue that all contributions are inherently technical in nature, at least to a certain degree.)

Not at all. Keep in mind, this post was extracted from another discussion so this is somewhat out of context.

My perspective comes from the opposite direction entirely.

My feeling is that the state of Fedora documentation is not ideal. There is not enough of it and what is there often goes out of date given how quickly Fedora makes changes.

Although I am not part of the inner workings of the documentation team, I strongly suspect that is due to not having enough active contributors.

I usually tend to approach these types of problems from “Is there a model that already works that can be adopted?”. In this case, that translates to “Are there any fast moving Linux distros that have documentation built and maintained by the community that is of high quality?”. There are two examples that I know of, Arch and Gentoo. How do they do it and what do they have in common?

The answer is that they both have lots of contributors because they make contribution as easy as possible. They both use a wiki where it is simple to contribute and there is almost no barrier to entry.

Next I thought about the Linux documentation projects I have been a part of and the contributions that people were willing to make and realized that I have seen lots of examples where people were willing to make “a contribution”. They were willing to write about something they were passionate about and had no plans to be frequent contributors outside of that one area of expertise/focus. People like that often have no desire to climb a hill and do a bunch of learning to for that one thing.

Based on the state of documentation in other projects and my own personal experiences working on Linux documentation, my belief is that the most important thing to good Linux documentation is making it easy to contribute. Anyone who thinks using git is very easy has lost perspective on what easy means.

Look at this way, there are lots of people who create an account on the Arch wiki and contribute a few sentences of documentation. Is someone likely to be motivated to go through a learning curve to do that? Some will, but many will not. However, having lots of people who contribute a few sentences is the difference between out-of-date docs and current docs.

This is an interesting point that probably needs further discussion. (Apologies in advance for pulling it out of context)

In my experience, I have seen lots of people contribute good Linux documentation who were not at all technical in nature. The days where all Linux users were inherently technical is in the past.

If we are talking about recruiting “Technical writers”, then sure, using git is reasonable. I simply believe that limiting it to only that audience won’t result in better documentation.

There is one last question I would ask. Is there an example of a Linux distro where the documentation is written entirely by volunteers where git is used to manage the documentation that is comprehensive and of high quality? If there is, what does that distro do differently than Fedora?

If the way Fedora is/has been doing their documentation is so much better than the Arch Wiki @dalto has referenced as a positive example of how effective documentation could be working for Fedora as well, then please all other posters in this thread (I can only mention up to 2 posters as a new user) tell me, why…

  1. Why do I as an average / noob user find better / more correct / more detailed, and more up-to-date information in the Arch Wiki about any problem, I might encounter as a USER of a different Distro(!)… than in Fedora Docs? - Why even after years in some cases is it much safer to rely on an Arch Wiki as a Fedora user???

  2. Why is it, that Fedora Docs is still full of old, overcome and factually wrong documentation? Example: Search Fedora(36) Docs for re-installation of Grub (a day-to-day problem for someone new to Fedora), and tell me, why is that info, if I click on F36 Docs still there, although it is totally incorrect, because at the time of writing it may have applied to Fedora 29, or 33 but since then was completely changed (and the changes are documented NO-WHERE)???

I need to let off some STEAM here, BIG TIME. Sorry, all!

So far, the Fedorans seem to come from an ivory tower, and there is nothing in scientific peer-review that justifies this jungle Fedora is presenting when it comes to documentation (and discussion… why 3-4 discussion boards?)…

So now… just my 2 cents as a noob. And thanks for considering my rant without any peer-review!

I think the Arch wiki just has a decent number of active and talented people on their Maintenance Team. As for how they managed to achieve that :person_shrugging:

I almost think Fedora should consider using Arch’s wiki as an “upstream”, clone it, and apply selective patches where necessary for Fedora Linux. :stuck_out_tongue: FWIW though, I’m fine with the current system. I think it just needs more people dedicated to working on it. I’m not convinced that making Fedora’s documentation more like ask.fp.o would be a good thing.

There goes my 1 cent…
The easier it is for a contribution, the better.
But the idea of pairs is excellent. So if it is possible to bring the two together, where a contribution/review is only published after being peer-reviewed, it seems to me the best way.
You just can’t inherit a bad characteristic of scientific production, where only one of your peers tells you that with ‘that comma, in that sentence’ he can’t release the article for publication… lol

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.

2 Likes

This is easy to answer—we lack the man power. We’ve not in recent years had an active team looking after the docs. It doesn’t matter what technology underlies it all—if we don’t have enough people updating the docs and regularly checking them for errors, they get outdated.

Same answer as above.

Have you filed issues about these? If you know what the correct information should be, could you please note that in the issue?

I don’t understand how scientific peer-review is meant to justify it—it’s a process that requires humans to implement it. No humans, no process.

Well, if you’d made this in a contribution to the docs, I can guarantee that the pull request would have required changes. Therein lies the difference between a forum and documentation :slight_smile:

I think we all agree that a major issue here is the lack of people-power. From my experience, it takes time to develop an active team in volunteer driven communities. Now that there’s an active core team looking after the docs here and more folks are joining in, this will improve over time, but it will not happen over night.

Can you please note what page does this so we can update it?

This is the core of the issue and the point I was trying to make.

If you want more people to work on documentation. Make it easier for a larger audience to contribute.

Of course, that isn’t the only thing that needs to be done but it is a component.

Also, please remember that my first post was originally a response in another topic that was split out here. I never intended it to read like using git was the only thing missing from magically have better documentation.

I just think that the complexity of the current process blocks many casual contributors. It is probably intimidating enough to even block some contributors who would be more than casual contributors.

In my experience, getting contributors for Linux documentation is a very difficult task so excluding some portion of those contributors is a mistake. Even if it the reasoning behind doing so is well thought out.

1 Like