Linux и документация с открытым исходным кодом — это беспорядок: вот решение
Простое обращение к RTFM не является ответом, если руководство устарело, нечитабельно или отсутствует. Нам необходимо улучшить качество нашей документации, и способ сделать это прост.
Когда я был заядлым пользователем и программистом Unix, ответом на любой технический вопрос был RTFM, что означает «Прочтите F… Fine Guide». К сожалению, ситуация не изменилась для поколений Linux и программного обеспечения с открытым исходным кодом. Пришло время решить эту проблему и добиться позитивных изменений. Руководства и почти вся документация часто устарели, иногда их практически невозможно прочитать, а иногда они даже не существуют.
Не то чтобы мы не знали об этой проблеме. Джон Корбет, редактор LWN, лучшего издания, посвященного Linux, и куратор документации по ядру Linux, говорит об этом с тех пор, как работает над Linux. Но никто никогда ничего с этим не делает.
Или, скорее, они это делают. Они стонут, жалуются, но работать над этим? Это похоже на то, как мыши кричат на кошку; все ноют об этом, но никто над этим не работает.
Это несправедливо. Некоторые люди усердно работали над документацией. Их просто недостаточно, и те, кто над этим работал, выгорают.
Действительно, Алехандро Коломар, который последние четыре года поддерживал проект справочных страниц Linux, только что уволился. Почему? Все просто, объяснил Коломар: «Я занимался этим в свободное время, и ни одна компания вообще не спонсировала эту работу… Я больше не могу поддерживать эту работу экономически».
Кто может его винить?
Как отметил Корбет: «Я часто жаловался, что, хотя тысячам разработчиков платят за работу над ядром Linux, нет ни одного человека, чья работа заключалась бы в написании документации для ядра».
Дело не в том, что никто не пишет документацию. Корбет продолжил: «Есть множество разработчиков, которые пишут документацию, не поймите меня неправильно; некоторые из них очень усердно над этим работают. Но обычно работодатели платят им за это не это».
Так происходит уже довольно давно. Несколькими годами ранее Корбет отметил, что «никто не хочет платить за документацию» и «нет никого, чья работа заключалась бы в написании документации для ядра». Отсутствие выделенных ресурсов приводит к некачественной документации.
Это проблема. Это настоящая проблема.
В частности, документация по ядру Linux уродлива. На собрании Linux Plumbers 2022 года Корбетт заметил:
Когда я впервые приступил к поддержке документации ядра, все было просто перенесено в основной каталог верхнего уровня. Предыдущий сопровождающий довольно хорошо описал это как «куда его уронил предыдущий случайный прохожий». Итак, мы улучшили это, но ситуация все еще напоминает мне спальню моей дочери, где вещи просто разбросаны куда попало. Это не к удаче, если вы хотите что-то найти.
С тех пор ситуация стала лучше, но, скажем так, она по-прежнему не дружелюбна к новичкам.
Не помогает и то, что документация ядра состоит из «тысяч отдельных документов», написанных изолированно, а не из связного корпуса документации. Несмотря на то, что были предприняты усилия по организации документов в книги для конкретных читателей, общей документации по-прежнему не хватает единой структуры.
Стив Ростедт, инженер-программист Google и разработчик ядра Linux, согласен. На прошлогодней конференции Linux Plumbers, как он сказал, «когда он сталкивается с ошибками, он не может найти документы, описывающие, как все работает». Если у кого-то такого старшего уровня, как Ростедт, возникнут проблемы, как вы думаете, насколько удачливым будет начинающий программист, пытающийся найти ответ на сложный вопрос?
Раз уж я говорил о Linux, позвольте мне заверить вас, что в других проектах с открытым исходным кодом дела обстоят не намного лучше. Многие из них, даже популярные, испытывают трудности с поддержанием полной и актуальной документации из-за недостаточного финансирования и быстрого развития. Я имею в виду, что когда ваши выпуски кода находятся в конвейере непрерывной интеграции/непрерывной доставки (CI/CD), который выпускает программы в производство каждый день или два, документация никогда не будет полностью актуальной.
Однако мы не говорим об актуальной документации. Я говорю об основных полезных документах и руководствах для разработчиков, системных администраторов и конечных пользователей.
Например, слишком многие проекты GitHub имеют мало документации, кроме файла README. Это бесполезно.
Другие проекты, похоже, просто не заботятся о документации. Возьмем, к примеру, мой любимый интерфейс рабочего стола Linux — Cinnamon. Многие люди используют его и любят его, но у него нет веб-сайта для конечных пользователей; все, что у него есть, — это страница на GitHub. Форумы и сообщество Linux Mint великолепны, но вам нужно серьезно покопаться, чтобы найти ответ на вашу ежедневную проблему.
Итак, что мы можем с этим поделать? На OpenSource.com имеется хороший список лучших практик документации.
Цените вклад в документацию так же, как и вклад в код.
Поместите документацию и код в один репозиторий проекта.
Сделайте документацию обязательным требованием для этапа слияния или выпуска.
-
Имейте последовательный процесс внесения кода и документации.
Иметь хорошо документированные процессы для участия в документации.
Замечательно. Удачи в том, чтобы люди ценили вклад в документацию так же, как и в код. Документация всегда была забытым детищем программирования.
Вот решение
Хотите узнать настоящий секрет улучшения проектной документации с открытым исходным кодом?
Готовый?
Заплатите авторам. Вот и все.
Написание документации — будь то 500-страничное руководство, быстрое и подробное руководство или часто задаваемые вопросы — это тяжелая работа. Поверьте мне. Я сделал все это, и, честно говоря, хотя я все еще время от времени пишу статьи с практическими рекомендациями для linux-terminal.com, никто не может заплатить мне достаточно, чтобы написать серьезную документацию, не говоря уже о технических руководствах. Это просто слишком много работы за недостаточно денег.
Однако у других людей есть талант и время. Чего у них нет, так это свободного времени. Коломар, например, кажется, готов снова подставить плечо к колесу страниц руководства, если кто-то ему заплатит.
Итак, если вы действительно хотите помочь Linux или вашему любимому проекту с открытым исходным кодом, договоритесь о том, чтобы платить реальные деньги программистам или технически подкованным писателям за написание документации. Мир технологий станет намного лучше.