Встречают по README — что нужно знать о документации
Сокращение времени на поиск информации — задача, о которой говорят непростительно мало. Эту задачу должны решать отдельные разработчики и, в целом, компании. Например, CloudMTS предоставляет материалы, чтобы пользователи быстро освоились и успешно работали в облаке. База знаний, с которой можно самостоятельно изучать облачные сервисы, это хорошее подспорье для беспроблемной миграции.
Проводя аналогию дальше, знакомство с новой разработкой может упросить файл README — базовый компонент документации.
Должны ли разработчики писать документацию? Как это часто бывает, однозначного ответа на этот вопрос нет.
Сегодня поговорим об инструментах для сборки и работы с README, а также обсудим тему документации.
Документационная дилемма
Наверное, самое распространенное мнение — каждый уважающий себя программист обязан документировать собственный код, в том числе достаточно очевидные моменты, нюансы которых можно упустить, если долгое время не возвращаться к написанному.
В то же время с кодовой базой могут взаимодействовать коллеги и, возможно, даже разработчики со стороны, у которых нет возможности «залезть» в голову автору. Кроме того, автор кода может вообще уйти из компании и тогда разобраться в программе станет еще сложнее.
Все эти факторы способны ограничить пространство для маневра команды в самый неподходящий момент. Если мы говорим про open source, то без качественных объяснений трудно привлечь к развитию проекта новых участников — им также будет сложнее разобраться в коде и принципах работы приложения.
Часть разработчиков настолько убеждена в необходимости составления документации, что возводит работу с ней в абсолют, практикуя подход Documentation First. В этом случае готовить документы начинают еще до того, как будет написана первая строчка кода.
В то же время существует параллельное мнение, что работа с документацией не должна заботить программиста. Одно дело — подготовить компактные, но исчерпывающие комментарии к коду. Cовершенно другое — Software Requirement Specification (SRS) — специальная документация для ПО которая содержит в себе информацию о том, как должна себя вести система, какие функции должна выполнять, какую нагрузку должна выдерживать и т. д.
Это задача для технических писателей, которые лучше знакомы с граничными кейсами и анти-паттернами, поэтому способны описать их более подробно.
Кроме того, мы часто преувеличиваем свою способность точно и понятно для других излагать мысли.
Психологи из Стэнфордского университета провели эксперимент: участник должен был настучать пальцами по столу популярную песню так, чтобы другой человек угадал ее.
Как вы думаете, с какой вероятностью правильно угадывали песню?
Всего 2,5%.
Как вы думаете, с какой вероятностью, по мнению участников, слушатели могут угадать мелодию?
50%.
Адам Грант, психолог и один из самых популярных докладчиков TED, в книге «Originals: How Non-Conformists Move the World» пишет, что ваши идеи становятся для вас слишком очевидны. Вы живете с ними долго, они плотно встроены в вашу картину миру, и поэтому вам кажется, что другие люди легко заметят очевидное. В результате люди доносят до окружающих во много раз меньше, чем могли бы, и чем нужно аудитории для понимания.
Какое это имеет отношение к написанию хорошей документации?
Документация становится неполной, поскольку она предполагает наличие большого количества знаний со стороны читателя.
Человек, который приходит документировать код со стороны, с точки зрения «пользователя», будет следить за тем, чтобы в руководстве не было пропущено ни одного шага.
Что интересно, некоторые специалисты считают тратой времени написание не только документации, но и комментариев к сложному коду. Писательство — сложная и ответственная задача, которая требует четкой организации мыслей, их критического рассмотрения и ясного выражения. Распространенной ошибкой является предположение, что авторы непонятного кода каким-то образом смогут ясно выражаться в комментариях.
Член экспертного совета IEEE Кевлин Хенни утверждает, что подготовить компактные, но исчерпывающие пояснения не так уж просто, поэтому разработчик может обойтись без комментирования, если пишет чистый и понятый код.
Иллюстрацией такого подхода может служить концепция «грамотного программирования», предложенная Дональдом Кнутом. Она гласит, что синтаксис алгоритмов должен напоминать естественный язык.
Другим применяемым на практике подходом является «самодокументирование кода» (self-documenting code). В этом случае программисты придерживаются установленных стандартов структурирования кода — так его становится легче воспринимать в рамках рабочих процессов.
О файлах README
Есть вопрос, по которому среди разработчиков не так уж много разногласий. Он касается необходимости составлять качественные файлы README для быстрого знакомства с программным обеспечением. Как правило, они содержат краткий обзор целей проекта, инструкции по установке, известные проблемы и, в большинстве случаев, руководство по быстрому старту для тех, кто знакомится с программой.
Как бы подчеркивая важность README-файлов, некоторые практикуют Readme Driven Development (по аналогии с Documentation Driven Development). Что интересно, среди его последователей числится Том Престон-Вернер, основатель GitHub. По его мнению, работа над файлом сведений позволяет заранее продумать логику и нюансы проекта, но при этом не сильно тормозит процесс разработки.
В качестве примера исчерпывающего README-файла можно привести документ gollum (вики-система, построенная на базе Git). Страница проекта в меру подробная и хорошо структурирована: есть разделы с описанием, системными требованиями, руководством по установке, конфигурациями и информацией для потенциальных спонсоров.
Авторы сделали шаг в сторону легкого для восприятия wiki-формата. Чтобы быстро составлять похожие файлы сведений, можно воспользоваться разными инструментами и даже прибегнуть к помощи сообщества.
Шаблоны для README
Существуют шаблоны, которые помогают составить базовый «скелет» README. Примером может быть опенсорсный Standard Readme, который распространяется по лицензии MIT.
Standard Readme состоит из спецификации и генератора файлов. Спецификация включает в себя рекомендации по написанию файлов сведений. Так, автор считает обязательными разделы, включающие название программного обеспечения, краткое описание, информацию по установке и лицензировании. Опциональными могут быть блоки про работу с API и вопросы информационной безопасности. К каждому из подразделов приложены инструкции — каким должен быть объем, какие инструменты использовать, как вставлять ссылки и примеры кода.
Что касается генератора Standard Readme, он помогает заполнить файл по описанному выше стандарту — для установки потребуется Node.js, пакетный менеджер npm и утилита Yeoman.
И похожих генераторов на рынке достаточно много, в том числе более комплексных. Так, Amazing GitHub Template (MIT License) помимо README позволяет генерировать файлы лицензий и документацию Code of Conduct. Сформировать их можно двумя способами — с помощью утилиты Cookiecutter (BSD 3-Clause), которая позволит вписать данные в полуавтоматическом режиме, либо вручную по шаблону.
С помощью подобных инструментов можно сформировать любой README-файл за несколько минут. Главное, не переусердствовать с оформлением. Cложная разметка может затруднить восприятие, поэтому важно соблюсти баланс смысла и формы.
Веб-конструкторы README
Другой вид инструментов — онлайн-редакторы README. Одним из наиболее развитых в этом направлении проектов можно назвать Readme.so. Приложение бесплатное (исходники выложены на GitHub), работает прямо в браузере, у него удобный интерфейс с поддержкой drag-and-drop — основные разделы README представлены в виде блоков, из которых как из конструктора можно собрать итоговый документ. При перетаскивании эти «кирпичики» автоматически заполняются шаблонными данными, которые можно использовать в качестве примера.
Еще один проект, который стоит упомянуть, — Make a README (MIT License). В нем уже представлены стандартные блоки с шаблонными данными в формате Markdown. Все вносимые изменения сразу отображаются в отдельном окне. Cразу видно, как соответствующий README-файл будет выглядеть на GitHub.
Существуют и менее специализированные веб-инструменты, такие как StackEdit. Приложение распространяется под лицензией Apache и позволяет создать любой шаблон с помощью разметки Markdown, а также средствами WYSIWYG-редактора. С его помощью можно составить не только README, но и другие документы. Кроме того, инструмент обеспечивает совместную работу — несколько человек могут одновременно редактировать файл и оставлять в нем комментарии.
Площадки для обратной связи
В целом ИТ-сообщество хорошо встречает подобные проекты, так как они упрощают подготовку базовой документации и частично автоматизируют процесс. Но бывает, что открытые инструменты поддерживают только один файловый формат — например, MD — и специалистам не хватает других вариантов (org, info, txt и т. д.).
Особая категория инструментов — это платформы и форумы, на которых энтузиасты помогают формировать и оценивают файлы README. Один из таких проектов на GitHub — Feedmereadmes. Его цель — создать среду, где можно получить помощь и обратную связь по составлению информационных файлов.
Работа площадки построена следующим образом: пользователи присылают свои README в раздел Issues репозитория и ждут обратной связи от коллег по цеху. Новый запрос на ревью появляется там примерно каждые две недели. По мнению авторов, Feedmereadmes может быть интересен разработчикам, которым сложно писать документацию; техническим писателям, которые хотят внести вклад в open source; и продакт-менеджерам, готовым поделиться экспертизой по части развития продуктов.
Есть специалисты, которые занимаются проверкой README в качестве хобби. Но проблема таких площадок в том, что обратную связь дают не всегда. Запросы часто остаются без ответа, так как все зависит от желания комьюнити участвовать в обмене опытом и мотивации членов сообщества.
