Документация по Linux и открытым исходным кодам находится в полном беспорядке: Вот решение

Если руководство устарело, нечитабельно или вообще отсутствует, просто сказать кому-то RTFM - это не выход. Нам необходимо повысить качество документации, и сделать это очень просто.

Когда я был начинающим пользователем Unix и программистом, то на любой технический вопрос отвечал RTFM, что означает «Прочтите это руководство». К сожалению, это не изменилось для поколений Linux и программного обеспечения с открытым исходным кодом. Настало время рассмотреть эту проблему и добиться положительных изменений. Руководства и почти вся документация часто устарели, иногда их почти невозможно прочитать, а иногда они даже не существуют.

Нельзя сказать, что мы не знаем об этой проблеме. Джон Корбет (Jon Corbet), редактор LWN, лучшей публикации о Linux с глубоким погружением, и куратор документации по ядру Linux, говорит об этом столько же, сколько работает в Linux. Но никто никогда ничего не делает для этого.

Или, скорее, делают. Они стонут, они жалуются, но работают над этим? Это как мыши бьют кота; все ноют об этом, но никто не работает над этим.

Это несправедливо. Некоторые люди усердно работают над документацией. Их просто не хватает, а те, кто работает над документацией, сгорают».

Действительно, Алехандро Коломар, который поддерживал проект Linux man-pages в течение последних четырех лет, только что уволился. Почему? Всё просто, объяснил Коломар: «Я занимался этим в свободное время, и ни одна компания не спонсировала эту работу. ... Я не могу больше экономически поддерживать эту работу».

Кто может его винить?

Как отметил Корбет, «я часто жаловался на то, что, хотя тысячи разработчиков получают зарплату за работу над ядром Linux, нет ни одного человека, в обязанности которого входило бы написание документации для ядра».

Дело не в том, что никто не пишет документацию. Корбет продолжает: «Есть много разработчиков, которые пишут документацию, не поймите меня неправильно; некоторые из них работают над этим очень усердно. Но обычно это не то, за что им платят работодатели».

Так было уже довольно давно. Несколькими годами ранее Корбет отмечал, что «никто не хочет платить за документацию» и «нет никого, чья работа заключалась бы в написании документации для ядра». Отсутствие специальных ресурсов приводит к тому, что документация получается некачественной.

Это проблема. Это реальная проблема.

В частности, документация по ядру Linux, ну, уродлива. На встрече Linux Plumbers в 2022 году Корбетт заметил:

Когда я только пришёл поддерживать документацию по ядру, всё было просто брошено в главный каталог верхнего уровня. Один из предыдущих сопровождающих описал его как «место, куда его бросил случайный прохожий». Так что мы улучшили это, но мы все еще находимся в ситуации, которая напоминает мне спальню моей дочери, где вещи были просто брошены где попало. Это не очень хорошая примета, если вы хотите что-то найти.

С тех пор ситуация улучшилась, но она все еще не является, скажем так, удобной для новичков.

Не помогает и то, что документация по ядру состоит из «тысяч отдельных документов», написанных по отдельности, а не как целостный свод документации. Хотя были предприняты усилия по организации документов в книги для конкретных читателей, общая документация все еще не имеет единой структуры.

Стив Ростедт, инженер-программист Google и разработчик ядра Linux, с этим согласен. На прошлогодней конференции Linux Plumbers он сказал, что «когда он сталкивается с ошибками, он не может найти документы, описывающие, как всё работает». Если у такого высокопоставленного человека, как Ростедт, возникают проблемы, то, как вы думаете, насколько повезет начинающему программисту, пытающемуся найти ответ на сложный вопрос?

Пока я говорю о Linux, позвольте заверить вас, что в других проектах с открытым исходным кодом дела обстоят не намного лучше. Многие из них, даже популярные, испытывают трудности с поддержанием полной и актуальной документации из-за недостатка средств и быстрого развития. Я имею в виду, что когда ваши кодовые релизы находятся в конвейере непрерывной интеграции/непрерывной доставки (CI/CD), который выпускает программы в производство каждый день или два, документация никогда не будет полностью актуальной.

Однако мы говорим не об актуальной документации. Я говорю об основных полезных документах и руководствах для разработчиков, системных администраторов и конечных пользователей.

Очень, очень много проектов на GitHub, например, не имеют ничего, кроме файла README для документации. Это не приносит пользы.

Другие проекты, похоже, просто не заботятся о документации. Возьмём, к примеру, мой любимый интерфейс рабочего стола Linux, Cinnamon. Многие люди используют его и любят, но у него нет сайта для конечных пользователей; всё, что у него есть - это страница на GitHub. Форумы и сообщество Linux Mint - это здорово, но вам придется серьезно покопаться, чтобы найти ответ на вашу актуальную проблему.

Итак, что мы можем сделать с этим? На сайте OpenSource.com есть хороший список лучших практик работы с документацией.

1. Цените вклад в документацию так же, как и вклад в код.
2. Размещайте документацию и код в одном репозитории проекта.
3. Сделайте документацию обязательным условием для слияния или релиза.
4. Иметь последовательный процесс внесения вклада в код и документацию.
5. Имеют хорошо документированные процессы для внесения вклада в документацию.

Это замечательно. Удачи вам в том, чтобы заставить людей ценить вклад в документацию так же высоко, как в код. Документация всегда была заброшенным ребенком программирования.

Вот решение

Хотите узнать настоящий секрет улучшения проектной документации с открытым исходным кодом?

Готовы?

Заплатите писателям. Вот и все.

Написание документации - будь то 500-страничное руководство, быстрый и грязный how-to или FAQ - это тяжелая работа. Поверьте мне. Я занимался всем этим, и, честно говоря, хотя я все еще буду время от времени писать статьи о том, как это делать, для ZDNET, никто не сможет заплатить мне достаточно, чтобы писать серьезную документацию, не говоря уже о технических руководствах. Это просто слишком много работы за недостаточные деньги.

Однако у других людей есть талант и время. Чего у них нет, так это свободного времени. Коломар, например, кажется, готов снова приложить плечо к колесу страниц руководства, если кто-то ему заплатит.

Поэтому, если вы действительно хотите помочь Linux или вашему любимому проекту с открытым исходным кодом, договоритесь платить реальные деньги программистам или технически подкованным писателям за написание документации. Мир технологий станет намного лучше.