Linux and open-source documentation is a mess: here’s the solution

When I was a novice Unix user and programmer, the standard answer to any technical question was RTFM, which stands for “Read the F… Fine Manual.” Unfortunately, this has not changed for the Linux and open source software generations. It is high time we address this problem and make positive change. The manuals and almost all documentation are often outdated, sometimes almost unreadable, and sometimes nonexistent.

Also: 10 Linux Apps I Can’t Live Without — And Why

It’s not that we don’t know about this problem. Jon Corbet, editor of LWN, the best in-depth Linux publication and the 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 whine, they complain, but work on it? It’s like mice belling the cat; everyone whines about it, but no one works on it.

That’s not fair. Some people have worked hard on the documentation. There just aren’t nearly enough of them, and those who have worked on it are burning out.

Alejandro Colomar, who has maintained the Linux man-pages project for the past four years, has just quit. Why? It’s simple, Colomar explained, “I did it in my spare time, and no company sponsored that work. … I can’t sustain this work economically anymore.”

Who can blame him?

Also: The bumpy road to upgrading from Ubuntu Linux 24.04

As Corbet noted, “I’ve often complained that even though thousands of developers are paid to work on the Linux kernel, there isn’t a single person writing the 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 hard at it. But that’s usually not what their employers pay them to do.”

This has been the case for some time. A few years earlier, Corbet had pointed out that “nobody wants to pay for documentation” and “there is no one 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.

The Linux kernel documentation in particular is, well, ugly. At the 2022 Linux Plumbers meeting, Corbett noted:

When I first started maintaining kernel documentation, everything was just thrown into the root directory at the top level. A previous maintainer described it quite well as “wherever someone dropped it.” So we fixed it, but we’re still in a situation that reminds me a lot of my daughter’s bedroom, where stuff is just thrown everywhere. It’s not a lucky thing to find something.

It’s gotten better since then, but it’s still not, let’s say, suitable for newcomers.

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

Also: I’ve been using 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 encounters bugs, he can’t find any documentation that describes how things work.” If someone as senior as Rostedt is having problems, how much luck do you think a novice programmer is going to have trying to figure out an answer to a difficult question?

While I’m on the subject of Linux, I can assure you that things aren’t much better in other open source projects. Many of them, even popular ones, struggle to maintain comprehensive and up-to-date documentation due to lack of funding and rapid development. I mean, if 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 are not talking about up-to-date documentation. I am talking about basic documents and guides for developers, system administrators and end users.

Also: Red Hat Introduces Enterprise Linux AI — and It’s Really Useful

For example, far, far too many GitHub projects have little more than a README file for documentation. That’s not helpful.

Other projects just don’t seem to care about documentation. Take my favorite Linux desktop interface, Cinnamon. Lots of 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 have to do some serious digging to find the answer to your problem of the day.

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

1. We value contributions to documentation as much as we value code.

2. Place documentation and code in the same project repository.

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

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

5. Ensure that you have well-documented processes for contributing to documentation.

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

Here is the solution

Want to know the real secret behind improving open source project documentation?

Finished?

Pay the writers. That’s all.

Also: The Most Popular Programming Languages ​​in 2024 (and What That 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 it all, and honestly, while I still write the occasional how-to article for ZDNET, no one can pay me enough to write serious documentation, let alone technical manuals. It’s just too much work for too little pay.

Others do have the talent and the time. What they don’t have is free time. Colomar, for example, seems prepared to put his shoulder under the wheel of the manuals again if someone pays him.

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