Документация играет важную роль в эффективной работе, особенно в условиях крупных и сложных инфраструктур. Она не только облегчает понимание существующих решений, но и ускоряет процесс интеграции новых технологий. Поэтом, например, важно иметь базу знаний по облачным технологиям.

Мы уже рассказывали об инструментах для сборки и работы с README. Сегодня перейдем к конкретным примерам для вдохновения: элементам, которые могут быть полезны в README: от блоков с пояснением лицензий до различных схем и диаграмм.

Быстро вникнуть в суть проекта

Файл README — это первое, что видят потенциальные пользователи open source-проекта. Его задача — быстро объяснить, что делает приложение (или утилита); дать разработчикам и специалистам понять, закрывает ли проект их потребности.

Решить эту задачу можно с помощью емких и понятных схем, наглядных GIF’ок или видео-демонстраций. Например, в репозитории проекта shallow-backup, предназначенного для резервного копирования конфигураций, шрифтов и пользовательских скриптов, в начале README размещен файл с анимацией (.gif), демонстрирующей работу утилиты в интерактивном режиме — с его помощью можно сразу оценить функциональность.

Больше примеров образцовых README-файлов приводят составители курируемой подборки Awesome README.

Так, авторы AREG SDK — открытого фреймворка для многозадачного программирования — проиллюстрировали концепцию «туманных вычислений»: как подключенные устройства взаимодействуют друг с другом и облачной инфраструктурой.

Другие схемы в репозитории отражают работу механизма удаленного вызова процедур и архитектуру самого фреймворка — как взаимодействуют локальные, публичные и интернет-сервисы.

В README инструмента ThePhish (служит для выявления фишинговых писем) тоже есть схемы. Одна описывает архитектуру, а другая — высокоуровневый алгоритм анализа писем с применением TheHive, Cortex и MISP.

Схемы могут быть полезными не только в описаниях сложных фреймворков — например, в репозитории с коллекцией шрифтов Nerd Fonts наглядная функциональная диаграмма иллюстрирует все доступные на данный момент наборы глифов.

Схемы, графики, другие методы визуализации действительно помогают лучше интерпретировать материал, быстрее погружаться в тему. Еще в 2011 году специалисты из университетов Пенсильвании, Джорджии и Невады изучили влияние схем и вспомогательных изображений на способности к запоминанию и восприятию информации. Они взяли статью о болезнях почек у космонавтов и предложили прочитать её двум группам участников. Одна читала только текст, другая — текст со схемами и графикой. В итоге члены второй группы показали лучшие способности к реинтерпретации.

Три профессора — из Университета Падерборна, Университета Мюнстера и Педагогического университета Людвигсбурга — провели метаанализ 41 научного труда с суммарным охватом, превышающим 10 тыс. респондентов. Авторы рассмотренных исследований, как правило, отмечали, что диаграммы, графики и модели способствовали погружению в тему.

Что поможет составить схемы

Существуют специальные инструменты, позволяющие упростить начертание схем и графов в файлах README. Например, Mermaid — язык для генерации диаграмм с помощью текста. Он работает в любой среде, поддерживающей GitHub UI, и позволяет отрисовывать диаграммы процессов, последовательностей, состояния, классов и другие (в целом процесс схож с вёрсткой Markdown-файлов).

Что ещё можно делать

В целом можно рисовать блок-схемы и с помощью ASCII-вёрстки — некоторые участники сообщества предпочитают такой формат. Ну а чтобы обойти трудности, связанные с форматированием и редактированием, можно использовать утилиту Markdeep. Она трансформирует ASCII-верстку в классические блок-схемы.

Освоить решение

Подробные примеры в README помогают пользователям быстро освоить инструмент и оценить его возможности. Например, в README веб-фреймворка Fiber (написанного на Go) авторы сразу приводят рабочий код: от инициализации приложения до запуска сервера. Они показывают, как организовать базовую маршрутизацию, назначать имена эндпоинтам, а также добавляют ссылки на разделы документации с более детальным разбором — например, по работе с middleware и предоставлением статических файлов.

Ещё один отличный пример — README скрипта FastColabCopy, который ускоряет загрузку файлов в Google Colab. В разделе с примерами приведены инструкции для быстрого старта, а также ссылка на расширенные сниппеты. Там можно найти код для монтирования Google Drive, установки autotime и fastcolabcopy, удаления временных системных файлов и экспорта списка файлов в txt.

Что поможет оформить примеры

Их стоит приводить в текстовом формате — так пользователи могут легко копировать и тестировать код. Однако, когда визуальная подача важнее функциональности, можно воспользоваться специальными инструментами, позволяющими превратить «скучный» код в красивую картинку. 

Например, есть Carbon с поддержкой 200+ языков программирования (в некоторых случаях он позволяет копировать код с изображения одним кликом). Другой open source-инструмент для презентации сниппетов — CodeImage. Он предлагает комплексный редактор с настройкой фоновых узоров, теней и рамок.

Разобраться, что можно, а что — нет

Разработчики часто игнорируют вопрос с понятной подачей выбранных ими лицензий. Казалось бы, пара строк в README — но именно они определяют, кто и как сможет использовать код: коммерческие компании, независимые разработчики или только исследователи и студенты. Лицензия, ни много ни мало, определяет дальнейшую судьбу open source-проекта и возможности для его развития.

В 2002 году известный программист Дуглас Крокфорд — создатель JSON и множества JavaScript-инструментов — выпустил несколько разработанных им библиотек под собственной лицензией на основе шаблона MIT. К её стандартному тексту он добавил формулировку: «Программное обеспечение должно использоваться во благо, а не во зло». Позже Крокфорд признался, что это была просто шутка, тем не менее юрист IBM однажды отправил разработчику официальный запрос на разрешение использовать его проект «в том числе и для зла» [вероятно, чтобы избежать возможных юридических последствий в будущем]. И разработчик решил дать свое официальное разрешение.

И даже спустя десятки лет на форумах всё ещё интересуются тем, что может грозить программисту, если он решит использовать ПО под этой модифицированной лицензией. Компании вроде Google не относят лицензию Крокфорда к категории open source ПО. А занимающаяся продвижением открытого программного обеспечения организация The Open Source Initiative и вовсе напрямую говорит, что open source-лицензии не могут ограничивать разработчиков «в вопросах добра и зла».

Так, к выбору лицензии стоит подходить осмотрительно — правила игры должны быть предельно ясны. Именно для этого в README нужна специальная секция, которая оперативно объяснит пользователям рамки дозволенного. Например, можно оформить её минималистично — как в репозитории amazing-github-template, где лицензия обозначена всего одной строкой. 

Или же выбрать развёрнутый формат, как в проекте Nerd Fonts: там используются шрифты из разных источников, каждый со своими условиями. Поэтому в README отражена ссылка на текст лицензии, раскрывающей правовые нюансы каждого компонента. 

Что поможет разобраться с лицензиями

Познакомиться с лучшими практиками можно в мини-курсе от специалистов GitHub.

Есть и проекты по теме на русском языке.