Linux- und Open-Source-Dokumentation ist ein Chaos: Hier ist die Lösung

Als ich ein unerfahrener Unix-Benutzer und Programmierer war, war RTFM die beste Antwort auf jede technische Frage, was für „Read the F… Fine Manual“ steht. Leider hat sich daran seit Generationen von Linux und Open-Source-Software nichts geändert. Es ist an der Zeit, dieses Problem anzugehen und positive Veränderungen herbeizuführen. Handbücher und fast die gesamte Dokumentation sind oft veraltet, manchmal kaum lesbar und manchmal existieren sie gar nicht.

Außerdem: 10 Linux-Apps, ohne die ich nicht leben kann – und warum

Es ist nicht so, dass wir dieses Problem nicht kennen. Jon Corbet, Herausgeber VSDer beste Linux-Publikations- und Linux-Kernel-Dokumentationswächter, hat darüber gesprochen, seit er an Linux gearbeitet hat. Allerdings hat niemand jemals etwas dagegen unternommen.

Oder genauer gesagt, sie taten es. Sie beschweren sich, sie beschweren sich, aber daran arbeiten? Es war, als würde eine Maus einer Katze eine Glocke läuten; Alle beschweren sich darüber, aber niemand arbeitet daran.

Das ist nicht fair. Einige Leute haben hart daran gearbeitet, Dinge zu dokumentieren. Die Zahlen reichen noch lange nicht aus und diejenigen, die daran arbeiten, sind erschöpft.

Tatsächlich hat Alejandro Colomar, der in den letzten vier Jahren das Linux-Manpages-Projekt geleitet hatte, kürzlich gekündigt. Warum? Es ist ganz einfach, erklärte Colomar: „Ich mache es in meiner Freizeitund kein einziges Unternehmen hat die Arbeit überhaupt gesponsert. … Ich kann es mir wirtschaftlich nicht länger leisten, diesen Job aufrechtzuerhalten.“

Wer könnte es ihm verdenken?

Außerdem: Der steile Weg zum Upgrade von Ubuntu Linux 24.04

Wie Corbet betont: „Ich beschwere mich oft darüber, dass, obwohl Tausende von Entwicklern dafür bezahlt werden, am Linux-Kernel zu arbeiten, Es gibt niemanden, dessen Aufgabe es ist, Dokumentationen zu schreiben für den Kernel.“

Das heißt nicht, dass niemand Dokumentation schreibt. Corbet fuhr fort: „Es gibt viele Entwickler, die Dokumentation schreiben, verstehen Sie mich nicht falsch; einige von ihnen haben ziemlich hart dafür gearbeitet. Allerdings ist das normalerweise nicht das, was ihnen ihre Arbeitgeber zahlen.“

Das passiert schon seit einiger Zeit. Einige Jahre zuvor hatte Corbet darauf hingewiesen, dass „Niemand möchte für die Dokumentation bezahlen„und „niemands Aufgabe ist es, Dokumentation für den Kernel zu schreiben.“ Dieser Mangel an dedizierten Ressourcen führt zu einer minderwertigen Dokumentation.

Das ist ein Problem. Das ist ein echtes Problem.

Insbesondere die Linux-Kernel-Dokumentation ist, nun ja, beschissen. Linux-Klempner 2022 Treffen sagte Corbett:

Als ich zum ersten Mal kam Pflegen Sie die Kernel-DokumentationAlles wird einfach im Hauptverzeichnis der obersten Ebene abgelegt. Ein früherer Betreuer beschrieb es ganz treffend als „wo auch immer ein früherer Passant es fallen ließ“. Also haben wir es repariert, aber wir befanden uns immer noch in einer Situation, die mich an das Schlafzimmer meiner Tochter erinnerte, wo Dinge einfach weggeworfen wurden. Es hat keinen Sinn, etwas zu suchen.

Es hat sich seitdem sicherlich verbessert, aber man könnte sagen, dass es immer noch nicht freundlich zu Neuankömmlingen ist.

Es hilft überhaupt nicht, dass die Kernel-Dokumentation aus „Tausende Einzeldokumente„separat geschrieben und nicht als zusammenhängende Dokumentationssammlung. Obwohl Anstrengungen unternommen wurden, Dokumente für bestimmte Zielgruppen in Büchern zu organisieren, mangelt es der gesamten Dokumentation immer noch an einer einheitlichen Struktur.

Außerdem: Ich benutze Linux seit 30 Jahren. Hier sind 5 Gründe, warum ich niemals auf Windows oder MacOS umsteigen werde

Steve Rostedt, ein Google-Softwareentwickler und Linux-Kernel-Entwickler, würde dem zustimmen. Auf der letztjährigen Ausstellung Linux-Klempner Konferenz sagte er: „Wenn er einen Fehler findet, kann er kein Dokument finden, das erklärt, wie etwas funktioniert.„Wenn sogar jemand so älter wie Rostedt Probleme hat, wie viel Glück wird Ihrer Meinung nach ein unerfahrener Programmierer haben, wenn er versucht, Antworten auf schwierige Fragen zu finden?

Während ich über Linux spreche, möchte ich Ihnen versichern, dass die Dinge bei anderen Open-Source-Projekten nicht viel besser sind. Viele von ihnen, auch beliebte, haben aufgrund unzureichender Finanzierung und schneller Entwicklung Schwierigkeiten, eine umfassende und aktuelle Dokumentation aufrechtzuerhalten. Ich meine, wenn Ihr Code-Release da ist Kontinuierliche Integration/kontinuierliche Lieferung (CI/CD) Bei Pipelines, die alle ein bis zwei Tage Programme für die Produktion freigeben, wird die Dokumentation nie vollständig auf dem neuesten Stand sein.

Allerdings handelt es sich hierbei nicht um aktuelle Dokumentation. Ich spreche von grundlegenden Dokumenten und Handbüchern, die für Entwickler, Systemadministratoren und Endbenutzer nützlich sind.

Außerdem: Red Hat bringt Enterprise Linux AI auf den Markt – und es ist wirklich nützlich

Zu viele Indonesisch: GitHub Das Projekt verfügt beispielsweise nur über eine README-Datei zur Dokumentation. Das hilft nicht.

Andere Projekte scheinen sich nicht um die Dokumentation zu kümmern. Nehmen Sie zum Beispiel meine Lieblings-Linux-Desktop-Oberfläche, ZimtViele Leute nutzen es und lieben es, haben aber keine Endbenutzer-Website; Alles, was es hat, ist eine GitHub-Seite. Jetzt, Forum Linux Mint und die Community ist großartig, aber Sie müssen ernsthaft recherchieren, um die Antwort auf Ihr aktuelles Problem zu finden.

Was können wir also dagegen tun? OpenSource.com eigen Liste guter Best Practices für die Dokumentation.

1. Schätzen Sie Beiträge zur Dokumentation ebenso wie Codebeiträge.

2. Legen Sie Dokumentation und Code im selben Projekt-Repository ab.

3. Machen Sie die Dokumentation zu einer Voraussetzung für Merge- oder Release-Meilensteine.

4. Verfügen Sie über einen konsistenten Beitragsprozess für Code und Dokumentation.

5. Verfügen Sie über einen gut dokumentierten Prozess für den Beitrag zur Dokumentation.

Sehr gut. Viel Glück dabei, die Leute dazu zu bringen, Dokumentationsbeiträge genauso zu schätzen wie Code. Dokumentation war schon immer ein vernachlässigter Teil der Programmierung.

Das ist die Lösung

Möchten Sie das wahre Geheimnis zur Verbesserung der Open-Source-Projektdokumentation erfahren?

Bereit?

Bezahle den Autor. Genau das.

Außerdem: Die beliebtesten Programmiersprachen im Jahr 2024 (und was sie bedeuten)

Das Schreiben einer Dokumentation – sei es ein 500-seitiges Handbuch, eine kurze und einfache Anleitung oder eine FAQ – ist eine Menge Arbeit. Vertrau mir. Ich habe das alles getan, und ehrlich gesagt, obwohl ich immer noch von Zeit zu Zeit Artikel mit Anleitungen für ZDNET schreibe, kann mir niemand genug bezahlen, um ernsthafte Dokumentationen zu schreiben, geschweige denn technische Handbücher. Zu viel Arbeit für zu wenig Geld.

Allerdings haben andere Leute das Talent und die Zeit. Was ihnen fehlt, ist Freizeit. Colomar zum Beispiel scheint bereit zu sein, wieder hart an den Manpages zu arbeiten, wenn jemand bereit ist, dafür zu zahlen.

Wenn Sie also wirklich Linux oder Ihr Lieblings-Open-Source-Projekt unterstützen möchten, zahlen Sie einem technisch versierten Programmierer oder Autor etwas Geld für das Schreiben der Dokumentation. Die Welt der Technologie wird ein viel besserer Ort sein.