Linux and open-source documentation is a mess: Here's the solution

When I was a wet-behind-the-ears Unix user and programmer, the go-to response to any tech question was RTFM, which stands for “Read the F… Fine Manual.” Unfortunately, this hasn’t changed for the Linux and open-source software generations. It’s high time we addressed this issue and brought about positive change. The manuals and almost all the documentation are often outdated, sometimes nearly impossible to read, and sometimes, they don’t even exist.

Also: 10 Linux apps I can’t do without – and why

It’s not like we don’t know about this problem. Jon Corbet, editor of LWN, the best deep-dive Linux publication and overseer of Linux kernel documentation, has been talking about it for as long as he’s been working on Linux. But no one ever does anything about it. 

Or, rather, they do. They moan, they complain, but work on it? It’s like the mice belling the cat; everyone whines about it, but no one works on it.

That’s not fair. Some people have worked hard on documentation. There are just nowhere near enough of them, and the ones who have been working on it are burning out. 

Indeed, Alejandro Colomar, who’s been maintaining the Linux man-pages project for the last four years, has just quit. Why? It’s simple, Colomar explained, “I’ve been doing it in my free time, and no company has sponsored that work at all.  … I cannot sustain this work economically anymore.” 

Who can blame him?

Also: The rocky road to upgrading Ubuntu Linux 24.04

As Corbet pointed out, “I have often complained that, even though thousands of developers are paid to work on the Linux kernel, there is not a single person whose job it is to write documentation for the kernel.” 

It’s not that no one writes documentation. Corbet continued, “There are plenty of developers who write documentation, don’t get me wrong; some of them work quite hard at it. But that is usually not what their employers are paying them to do.”

This has been the case for quite some time. A few years earlier, Corbet had pointed out that “Nobody wants to pay for documentation” and “there is nobody whose job it is to write documentation for the kernel.” This lack of dedicated resources results in poor-quality documentation.

That’s a problem. That’s a real problem.

In particular, Linux kernel documentation is, well, ugly. At the 2022 Linux Plumbers meeting, Corbett remarked: 

When I first came in to maintain kernel documentation, everything was just kind of thrown into the main top-level directory. A previous maintainer described it pretty well as ‘wherever a previous random passerby had dropped it.’ So we improved it, but we’re still in a situation that reminds me a lot of my daughter’s bedroom, where things have just been thrown wherever. It’s not good luck if you want to find something.

It’s gotten better since then, but it’s still not, shall we say, newcomer-friendly. 

It doesn’t help any that kernel documentation consists of “thousands of individual documents” written in isolation rather than a coherent body of documentation. While efforts have been made to organize documents into books for specific readers, the overall documentation still lacks a unified structure.

Also: I’ve used Linux for 30 years. Here are 5 reasons why I’ll never switch to Windows or MacOS

Steve Rostedt, a Google software engineer and Linux kernel developer, would agree. At last year’s Linux Plumbers conference, he said, “when he runs into bugs, he can’t find documents describing how things work.” If someone as senior as Rostedt has trouble, how much luck do you think a novice programmer will have trying to find an answer to a difficult question?

While I’ve been talking about Linux, let me assure you that things are not that much better in other open-source projects. Many of them, even popular ones, struggle with maintaining comprehensive and up-to-date documentation due to insufficient funds and rapid development. I mean, when your code releases are in a Continuous Integration/Continuous Delivery (CI/CD) pipeline that releases programs to production every day or two, the documentation will never be completely up to date.

However, we’re not talking about up-to-date documentation. I’m talking about basic useful documents and manuals for developers, system administrators, and end-users. 

Also: Red Hat unleashes Enterprise Linux AI – and it’s truly useful

Way, way too many GitHub projects, for instance, have little but a README file for documentation. That’s not helpful.

Other projects just don’t seem to care about documentation. Take, for example, my favorite Linux desktop interface, Cinnamon. Many people use it and love it, but it doesn’t have an end-user website; all it has is its GitHub page.  Now, the Linux Mint Forums and community are great, but you need to do some serious digging to find the answer for your problem du jour.

So, what can we do about this? OpenSource.com has a good list of documentation best practices. 

1. Value contributions to documentation just as much as code contributions. 

2. Put documentation and code in the same project repo. 

3. Make documentation a requirement for a merge or release milestone.

4. Have a consistent contribution process for code and documentation.

5. Have well-documented processes for contributing to documentation.

That’s great. Good luck getting people to value documentation contributions as much as code. Documentation has always been the neglected child of programming.  

Here’s the solution

Do you want to know the real secret-sauce of improving open-source project documentation? 

Ready?

Pay the writers. That’s it. 

Also: The most popular programming languages in 2024 (and what that even means)

Writing documentation — whether it’s a 500-page manual, a quick and dirty how-to, or an FAQ — is hard work. Trust me. I’ve done all of these, and frankly, while I’ll still write how-to articles for ZDNET from time to time, no one can pay me enough to write serious documentation, never mind technical manuals. It’s simply too much work for not enough money.

Other people, though, do you have the talent and the time. What they don’t have is free time. Colomar, for example, seems willing to put his shoulder to the manual pages wheel again if someone will pay him.

So, if you really want to help Linux or your favorite open-source project, arrange to pay real money to programmers or tech-savvy writers to write documentation. The tech world will be a much better place.