Код программы, написанный на Java, C ++ или любом другом языке, сложно документировать в частности потому, что технические писатели часто не владеют языком программирования. Но даже для писателей или разработчиков, свободно владеющих языком, эта задача может быть трудной. Отсутствует пошаговый процесс, которому надо следовать. Код часто упорядочен в нелинейном порядке, поэтому не получится просто идти построчно по нему. Существует также вопрос о том, сколько документировать, что покрывать и куда включать документацию. В целом, лучшие практики документирования кода нечеткие и неопределенные, что делает документирование кода одной из самых сложных и трудоемких задач, стоящих перед техническими авторами.
В разделе Описание и образцы кода есть упоминание о важности документирования кода. Но, учитывая важность этой темы, мы рассмотрим ее шире в этом разделе.
Содержание раздела
Свежий опыт документирования кода
Проблема 1: Код не следует пошаговой парадигме
Проблема 2: Аудитория может иметь разный технический уровень
Проблема 3: Код требует понимания конкретного языка программирования
Проблема 4: Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки
Проблема 5: У инженеров гораздо лучше наметан глаз на хороший и плохой код
Важность документирования кода
Абстрактные темы хорошо подкреплять реальным опытом. Недавний проект, над которым работал автор курса - разработка логики бэкенда для голосового управления приложением Fire TV, чтобы пользователи могли сказать «Play Interstellar» (или название другого фильма), и приложение запустить этот фильм.
Когда пользователи произносят команды голосовому помощнику Alexa, Alexa интерпретирует команды и упаковывает информацию в структурированный JSON-запрос на отправку партнеру кода Lambda. Lambda, сервис AWS, обеспечивает внесерверные вычисления. Предполагается, что партнеры прослушивают входящие запросы, а затем выдают собственный код для надлежащего ответа на запросы, предположительно получая идентификатор для Instellar (в этом примере) и отправляя этот идентификатор в свое приложение Fire TV для воспроизведения.
Реализация включала в себя кодирование лямбда-функции. Чтобы помочь разработчикам, инженеры предоставили пример лямбда-функции (в Node JS), но без объяснения причин. Работая над документацией, возникла потребность пояснения логики лямбда-кода.
Лямбда-код написан на 450 строках и не очень сложен. Не зная Lambda или Node JS, пришлось много изучить, чтобы понять, что происходит в каждой строке. В подходе к документированию кода объясняются условия, которые инициировали лямбда-код для вызова в первую очередь. Затем лямбда-код был показан полностью, чтобы у пользователя был контекст. Затем код был разделен на четыре отдельных логических раздела. Под полным примером кода был представлен каждый раздел (помечая их как пояснение к разделу 1, объяснение к разделу 2 и т.д.), Пока не был пройден весь пример кода.
Такой подход был не особо хорош, но другого метода не было. Хотелось бы подробнее остановиться на каждом из раздело, а не просто делать краткие комментарии. Полученную документацию можете увидеть здесь: Шаг 3: Понимание директив Alexa и лямбда-ответов (мультимодальные устройства). Нет сомнений в том, что эта документация скоро изменится, поэтому подробностей, помимо описанного подхода, нет. Но такой подход можно рассматривать как введение в проблему документирования кода.
В целом, документирование кода, пожалуй, самый сложный аспект технического писательства, особенно для не инженеров. Ниже описаны несколько причин, почему документирование кода ставит так много проблем.
Код нелинейный. То, что появляется вверху (например, переменные), может не реализовываться до функций, определенных внизу. Функции, определенные внизу, могут выполняться внутри других блоков кода в середине и т.д. Порядок сборки фрагмента кода вообще неочевиден.
Основная парадигма, которой следуют большинство технических писателей, - это модель, основанная на задачах, где вы начинаете с шагов 1, 2, 3 и так далее, пока не достигнете конца задачи. Это не относится к документации по коду. Код является нелинейным по своей природе, поэтому нельзя просто начать сверху и перейти к нижней части. Могут быть лучшие практики, дополнительные методы, списки параметров, концептуальные объяснения в сочетании с другими деталями и многое другое. Стратегия документирования кода состоит в том, чтобы представить полный пример кода, за которым следуют разделы, которые объясняют различные аспекты кода. Такой подход очень отличается от процедурного подхода, обычно применяемого в технических документах.
Другой проблемой, с которой пришлось столкнулся, это понимание, что нужно объяснять, а что можно пропустить. Разбираются ли разработчики уже в обработчиках в Lambda и Node JS? Или это для них новинка?
Технический писатель должен писать в соответствии с уровнем знаний своей аудитории, даже если технические уровни разных аудиторий сильно различаются. Документация обычно либо переписывается для продвинутых разработчиков, объясняя очевидное, либо отталкивает менее опытных разработчиков, поясняя слишком много. Реализация прогрессивных моделей раскрытия информации может быть сложной. Даже если аудитория технически грамотная, она не гарантирует, что у нее есть опыт в конкретной технологии, которая документируется. В результате, мы, технические писатели, часто представляем себя аудиторией.
Исходя из упомянутого пункта выше об аудитории получаем следующий факт.
Технические писатели часто не знакомы с языком программирования, или, если технические писатели знакомы с программированием, проект может быть на незнакомом языке. Таким образом, мы сразу же оказываемся в невыгодном положении и вынуждены пользоваться учебными пособиями, чтобы понять основы того, что происходит в коде. Но мы не документируем основы - мы документируем, как реализовать код в определенном контексте, часто на продвинутом уровне. Знание того, как работает код, просто предполагается. Мы должны пройти курс Advanced Calculus и объяснить множители Legrange, зная простую алгебру.
Другая задача: понимать, что пример кода работает от релиза к релизу.
Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Часть кода может просто выполняться достаточно легко, но иногда может и потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения.
Наконец стоит отметить, что, иногда, при документировании кода можно почувствовать себя немного посторонним, как будто пишущим о культуре или стране, к которой не принадлежишь. Технические писатели часто являются посторонними для разработчика. Не будучи разработчиком, можно даже не осознавать, что ваш код плохой.
Помните, что инженеры живут и дышат кодом, и многие считают, что код - это поэзия. Эффективная техника в коде (например, рекурсивные циклы, которые расширяют ресурсы по мере необходимости) может быть прекрасной, вызывая эстетику в уме инженера. Маловероятно, что технический писатель будет подходить к коду с таким же почтением и благоговением. Более приземленный подход к коду может затруднить работу с разработчиками.
Несмотря на трудности документирования кода, эту область документации не следует упускать из виду. Спросите разработчиков, что является наиболее важным элементом документации API, и ответ, который вы обязательно услышите снова и снова, - это примеры кода. Включайте образцы рабочего кода, которые разработчики могут легко скопировать и вставить в свою документацию. Примеры кода, которые продемонстрируют, как включить абстракции в реальную реализацию.
Примеры кода, примеры приложений - независимо от формы, просто нужно больше кода!!!
Ниже видео инженера Рути Бен Дор на конференции «Write the Docs». На вопрос: «Каковы три наиболее важных элемента создания документации API?», Рут ответил (на 4:15):
Я думаю, если вы собираетесь создавать документацию по API, есть три вещи, которые следует либо включить в нее, либо сделать в процессе ее создания. Я думаю, самое важное, если вы хотите, чтобы люди просто начали его использовать, это примеры кода. Существует множество генераторов документации API, которые будут генерировать примеры кода для вас. Иногда они не очень хороши, поэтому нужно иметь кого-то на самом деле, кто проверил бы эти примеры кода, чтобы убедиться, что они действительно работают правильно. Одно дело получить метод и то, как он вызывается, но для разработчика нужно взять его и понять, как создать рабочий код, достигнув этой конечной точки, это совершенно другое. В отличие от того, могут ли они просто копировать и вставлять в консоль браузера, чтобы доказать, что она работает для себя, это действительно хороший способ снизить барьер для входа. Примеры кода огромны, и примеры кода на разных языках, которые люди могут использовать с вашим API.
Почему инженеры постоянны в своем желании видеть код? Примеры кода показывают, как реализовать абстрактное, повествовательное объяснение фактическим способом. В этом смысле они являются чрезвычайно мощными инструментами, помогающими пользователям понять правильные действия.
Несмотря на важность примеров кода, их нелегко реализовать. По этой причине они часто игнорируются или отсутствуют в документации API. На самом деле, примеры кода могут быть самой сложной частью документации, которую должны документировать технические писатели. В этом разделе разберемся, почему документирование кода может быть сложной задачей, а затем в дополнительных темах рассмотрим конкретные стратегии для успешного включения примеров кода в документацию.