After I was a wet-behind-the-ears Unix consumer and programmer, the go-to response to any tech query was RTFM, which stands for “Learn the F… Positive Handbook.” Sadly, this hasn’t modified for the Linux and open-source software program generations. It is excessive time we addressed this subject and caused constructive change. The manuals and virtually all of the documentation are sometimes outdated, typically practically unattainable to learn, and typically, they do not even exist.
Additionally: 10 Linux apps I can’t do without – and why
It isn’t like we do not learn about this downside. Jon Corbet, editor of LWN, one of the best deep-dive Linux publication and overseer of Linux kernel documentation, has been speaking about it for so long as he is been engaged on Linux. However nobody ever does something about it.
Or, quite, they do. They moan, they complain, however work on it? It is just like the mice belling the cat; everybody whines about it, however nobody works on it.
That is not honest. Some individuals have labored laborious on documentation. There are simply nowhere close to sufficient of them, and those who’ve been engaged on it are burning out.
Certainly, Alejandro Colomar, who’s been sustaining the Linux man-pages challenge for the final 4 years, has simply give up. Why? It is easy, Colomar defined, “I’ve been doing it in my free time, and no firm has sponsored that work in any respect. … I can’t maintain this work economically anymore.”
Who can blame him?
Additionally: The rocky road to upgrading Ubuntu Linux 24.04
As Corbet identified, “I’ve usually complained that, regardless that hundreds of builders are paid to work on the Linux kernel, there’s not a single person whose job it is to write documentation for the kernel.”
It isn’t that nobody writes documentation. Corbet continued, “There are many builders who write documentation, do not get me fallacious; a few of them work fairly laborious at it. However that’s often not what their employers are paying them to do.”
This has been the case for fairly a while. A number of years earlier, Corbet had identified that “Nobody wants to pay for documentation” and “there’s no one whose job it’s to write down documentation for the kernel.” This lack of devoted sources leads to poor-quality documentation.
That is an issue. That is an actual downside.
Specifically, Linux kernel documentation is, nicely, ugly. On the 2022 Linux Plumbers assembly, Corbett remarked:
After I first got here in to maintain kernel documentation, all the things was simply form of thrown into the principle top-level listing. A earlier maintainer described it fairly nicely as ‘wherever a earlier random passerby had dropped it.’ So we improved it, however we’re nonetheless in a scenario that jogs my memory a number of my daughter’s bed room, the place issues have simply been thrown wherever. It isn’t good luck if you wish to discover one thing.
It is gotten higher since then, but it surely’s nonetheless not, shall we embrace, newcomer-friendly.
It does not assist any that kernel documentation consists of “thousands of individual documents” written in isolation quite than a coherent physique of documentation. Whereas efforts have been made to prepare paperwork into books for particular readers, the general documentation nonetheless lacks a unified construction.
Additionally: 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 program engineer and Linux kernel developer, would agree. Eventually 12 months’s Linux Plumbers convention, he mentioned, “when he runs into bugs, he can’t find documents describing how things work.” If somebody as senior as Rostedt has bother, how a lot luck do you suppose a novice programmer can have looking for a solution to a troublesome query?
Whereas I have been speaking about Linux, let me guarantee you that issues usually are not that significantly better in different open-source tasks. A lot of them, even widespread ones, wrestle with sustaining complete and up-to-date documentation on account of inadequate funds and speedy growth. I imply, when your code releases are in a Continuous Integration/Continuous Delivery (CI/CD) pipeline that releases packages to manufacturing day-after-day or two, the documentation won’t ever be fully updated.
Nevertheless, we’re not speaking about up-to-date documentation. I am speaking about primary helpful paperwork and manuals for builders, system directors, and end-users.
Additionally: Red Hat unleashes Enterprise Linux AI – and it’s truly useful
Means, means too many GitHub tasks, for example, have little however a README file for documentation. That is not useful.
Different tasks simply do not appear to care about documentation. Take, for instance, my favourite Linux desktop interface, Cinnamon. Many individuals use it and like it, but it surely does not have an end-user web site; all it has is its GitHub web page. Now, the Linux Mint Forums and neighborhood are nice, however it is advisable to do some critical digging to seek out the reply to your downside du jour.
So, what can we do about this? OpenSource.com has a good list of documentation best practices.
-
Worth contributions to documentation simply as a lot as code contributions.
-
Put documentation and code in the identical challenge repo.
-
Make documentation a requirement for a merge or launch milestone.
-
Have a constant contribution course of for code and documentation.
-
Have well-documented processes for contributing to documentation.
That is nice. Good luck getting individuals to worth documentation contributions as a lot as code. Documentation has all the time been the uncared for baby of programming.
Here is the answer
Do you wish to know the true secret-sauce of bettering open-source challenge documentation?
Prepared?
Pay the writers. That is it.
Additionally: The most popular programming languages in 2024 (and what that even means)
Writing documentation — whether or not it is a 500-page handbook, a fast and soiled how-to, or an FAQ — is tough work. Belief me. I’ve achieved all of those, and albeit, whereas I will nonetheless write how-to articles for ZDNET on occasion, nobody pays me sufficient to write down critical documentation, by no means thoughts technical manuals. It is merely an excessive amount of work for not sufficient cash.
Different individuals, although, do you might have the expertise and the time. What they do not have is free time. Colomar, for instance, appears prepared to place his shoulder to the handbook pages wheel once more if somebody pays him.
So, in case you actually wish to assist Linux or your favourite open-source challenge, organize to pay actual cash to programmers or tech-savvy writers to write down documentation. The tech world shall be a significantly better place.
