Once 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… High quality Guide.” Sadly, this hasn’t modified for the Linux and open-source software program generations. It is excessive time we addressed this challenge and led to constructive change. The manuals and virtually all of the documentation are sometimes outdated, typically almost inconceivable 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 find out about this drawback. Jon Corbet, editor of LWN, the perfect 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, fairly, 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 venture 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 not maintain this work economically anymore.”
Who can blame him?
Additionally: The rocky road to upgrading Ubuntu Linux 24.04
As Corbet identified, “I’ve typically complained that, though hundreds of builders are paid to work on the Linux kernel, there may be 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 flawed; a few of them work fairly laborious at it. However that’s normally not what their employers are paying them to do.”
This has been the case for fairly a while. A couple of years earlier, Corbet had identified that “Nobody wants to pay for documentation” and “there may be no person 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 drawback.
Particularly, Linux kernel documentation is, effectively, ugly. On the 2022 Linux Plumbers assembly, Corbett remarked:
Once I first got here in to maintain kernel documentation, every part was simply form of thrown into the primary top-level listing. A earlier maintainer described it fairly effectively as ‘wherever a earlier random passerby had dropped it.’ So we improved it, however we’re nonetheless in a state of affairs that jogs my memory quite a lot 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, let’s consider, newcomer-friendly.
It does not assist any that kernel documentation consists of “thousands of individual documents” written in isolation fairly than a coherent physique of documentation. Whereas efforts have been made to arrange 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. Ultimately 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 assume 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 are usually not that a lot better in different open-source initiatives. A lot of them, even standard ones, battle with sustaining complete and up-to-date documentation as a consequence of inadequate funds and fast improvement. I imply, when your code releases are in a Continuous Integration/Continuous Delivery (CI/CD) pipeline that releases packages to manufacturing day by day or two, the documentation won’t ever be utterly 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
Method, approach too many GitHub initiatives, for example, have little however a README file for documentation. That is not useful.
Different initiatives 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 group are nice, however you could do some severe digging to search out the reply on your drawback 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 venture 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 at all times been the uncared for little one of programming.
This is the answer
Do you need to know the true secret-sauce of enhancing open-source venture 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 guide, a fast and soiled how-to, or an FAQ — is tough work. Belief me. I’ve accomplished all of those, and albeit, whereas I am going to nonetheless write how-to articles for ZDNET every now and then, nobody will pay me sufficient to write down severe documentation, by no means thoughts technical manuals. It is merely an excessive amount of work for not sufficient cash.
Different individuals, although, do you will have the expertise and the time. What they do not have is free time. Colomar, for instance, appears keen to place his shoulder to the guide pages wheel once more if somebody can pay him.
So, for those who actually need to assist Linux or your favourite open-source venture, organize to pay actual cash to programmers or tech-savvy writers to write down documentation. The tech world shall be a a lot better place.