diff --git a/doc-code/doc-code.md b/doc-code/doc-code.md index 49c4dd2..10a367b 100644 --- a/doc-code/doc-code.md +++ b/doc-code/doc-code.md @@ -24,26 +24,62 @@ [Важность документирования кода](#importance) -## Свежий опыт документирования кода(#) +## Свежий опыт документирования кода + +Абстрактные темы хорошо подкреплять реальным опытом. Недавний проект, над которым работал автор курса - разработка логики бэкенда для голосового управления приложением Fire TV, чтобы пользователи могли сказать «Play Interstellar» (или название другого фильма), и приложение запустить этот фильм. + +Когда пользователи произносят команды голосовому помощнику Alexa, Alexa интерпретирует команды и упаковывает информацию в структурированный JSON-запрос на отправку партнеру кода Lambda. Lambda, сервис AWS, обеспечивает внесерверные вычисления. Предполагается, что партнеры прослушивают входящие запросы, а затем выдают собственный код для надлежащего ответа на запросы, предположительно получая идентификатор для Instellar (в этом примере) и отправляя этот идентификатор в свое приложение Fire TV для воспроизведения. + +Реализация включала в себя кодирование лямбда-функции. Чтобы помочь разработчикам, инженеры предоставили пример лямбда-функции (в Node JS), но без объяснения причин. Работая над документацией, возникла потребность пояснения логики лямбда-кода. + +Лямбда-код написан на 450 строках и не очень сложен. Не зная Lambda или Node JS, пришлось много изучить, чтобы понять, что происходит в каждой строке. В подходе к документированию кода объясняются условия, которые инициировали лямбда-код для вызова в первую очередь. Затем лямбда-код был показан полностью, чтобы у пользователя был контекст. Затем код был разделен на четыре отдельных логических раздела. Под полным примером кода был представлен каждый раздел (помечая их как пояснение к разделу 1, объяснение к разделу 2 и т.д.), Пока не был пройден весь пример кода. + +Такой подход был не особо хорош, но другого метода не было. Хотелось бы подробнее остановиться на каждом из раздело, а не просто делать краткие комментарии. Полученную документацию можете увидеть здесь: [Шаг 3: Понимание директив Alexa и лямбда-ответов (мультимодальные устройства)](https://developer.amazon.com/docs/video-skills-multimodal-devices/understand-directives-and-responses.html). Нет сомнений в том, что эта документация скоро изменится, поэтому подробностей, помимо описанного подхода, нет. Но такой подход можно рассматривать как введение в проблему документирования кода. + +В целом, документирование кода, пожалуй, самый сложный аспект технического писательства, особенно для не инженеров. Ниже описаны несколько причин, почему документирование кода ставит так много проблем. ## Проблема 1: Код не следует пошаговой парадигме +Код нелинейный. То, что появляется вверху (например, переменные), может не реализовываться до функций, определенных внизу. Функции, определенные внизу, могут выполняться внутри других блоков кода в середине и т.д. Порядок сборки фрагмента кода вообще неочевиден. + +Основная парадигма, которой следуют большинство технических писателей, - это модель, основанная на задачах, где вы начинаете с шагов 1, 2, 3 и так далее, пока не достигнете конца задачи. Это не относится к документации по коду. Код является нелинейным по своей природе, поэтому нельзя просто начать сверху и перейти к нижней части. Могут быть лучшие практики, дополнительные методы, списки параметров, концептуальные объяснения в сочетании с другими деталями и многое другое. Стратегия документирования кода состоит в том, чтобы представить полный пример кода, за которым следуют разделы, которые объясняют различные аспекты кода. Такой подход очень отличается от процедурного подхода, обычно применяемого в технических документах. + ## Проблема 2: Аудитория может иметь разный технический уровень +Другой проблемой, с которой пришлось столкнулся, это понимание, что нужно объяснять, а что можно пропустить. Разбираются ли разработчики уже в обработчиках в Lambda и Node JS? Или это для них новинка? + +Технический писатель должен писать в соответствии с уровнем знаний своей аудитории, даже если технические уровни разных аудиторий сильно различаются. Документация обычно либо переписывается для продвинутых разработчиков, объясняя очевидное, либо отталкивает менее опытных разработчиков, поясняя слишком много. Реализация прогрессивных моделей раскрытия информации может быть сложной. Даже если аудитория технически грамотная, она не гарантирует, что у нее есть опыт в конкретной технологии, которая документируется. В результате, мы, технические писатели, часто представляем себя аудиторией. + ## Проблема 3: Код требует понимания конкретного языка программирования +Исходя из упомянутого пункта выше об аудитории получаем следующий факт. + +Технические писатели часто не знакомы с языком программирования, или, если технические писатели знакомы с программированием, проект может быть на незнакомом языке. Таким образом, мы сразу же оказываемся в невыгодном положении и вынуждены пользоваться учебными пособиями, чтобы понять основы того, что происходит в коде. Но мы не документируем основы - мы документируем, как реализовать код в определенном контексте, часто на продвинутом уровне. Знание того, как работает код, просто предполагается. Мы должны пройти курс Advanced Calculus и объяснить множители Legrange, зная простую алгебру. + ## Проблема 4: Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки +Другая задача: понимать, что пример кода работает от релиза к релизу. + +Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Часть кода может просто выполняться достаточно легко, но иногда может и потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения. + ## Проблема 5: У инженеров гораздо лучше наметан глаз на хороший и плохой код +Наконец стоит отметить, что, иногда, при документировании кода можно почувствовать себя немного посторонним, как будто пишущим о культуре или стране, к которой не принадлежишь. Технические писатели часто являются посторонними для разработчика. Не будучи разработчиком, можно даже не осознавать, что ваш код плохой. + +Помните, что инженеры живут и дышат кодом, и многие считают, что код - это поэзия. Эффективная техника в коде (например, рекурсивные циклы, которые расширяют ресурсы по мере необходимости) может быть прекрасной, вызывая эстетику в уме инженера. Маловероятно, что технический писатель будет подходить к коду с таким же почтением и благоговением. Более приземленный подход к коду может затруднить работу с разработчиками. + ## Важность документирования кода +Несмотря на трудности документирования кода, эту область документации не следует упускать из виду. Спросите разработчиков, что является наиболее важным элементом документации API, и ответ, который вы обязательно услышите снова и снова, - это примеры кода. Включайте образцы рабочего кода, которые разработчики могут легко скопировать и вставить в свою документацию. Примеры кода, которые продемонстрируют, как включить абстракции в реальную реализацию. + +Примеры кода, примеры приложений - независимо от формы, просто нужно больше кода!!! + Ниже видео инженера Рути Бен Дор на конференции «Write the Docs». На вопрос: «Каковы три наиболее важных элемента создания документации API?», Рут ответил (на 4:15): @@ -55,23 +91,6 @@ Несмотря на важность примеров кода, их нелегко реализовать. По этой причине они часто игнорируются или отсутствуют в документации API. На самом деле, примеры кода могут быть самой сложной частью документации, которую должны документировать технические писатели. В этом разделе разберемся, почему документирование кода может быть сложной задачей, а затем в дополнительных темах рассмотрим конкретные стратегии для успешного включения примеров кода в документацию. - -## Проблемы документирования когда - -Рассмотрим несколько причин, почему документирование кода это сложная задача - -- **Код требует понимания конкретного языка программирования.** Технические писатели часто не знакомы с языком программирования, или, если технические писатели знакомы с программированием, проект может быть на незнакомом языке. Таким образом, мы сразу же оказываемся в невыгодном положении и вынуждены пользоваться учебными пособиями, чтобы понять основы того, что происходит в коде. Но мы не документируем основы - мы документируем, как реализовать код в определенном контексте, часто на продвинутом уровне. Знание того, как работает код, просто предполагается. Мы должны пройти курс Advanced Calculus и объяснить множители Legrange, зная простую алгебру. -- **Код не следует пошаговой парадигме.** Основная парадигма, которой следуют большинство технических писателей, - это модель, основанная на задачах, где вы начинаете с шагов 1, 2, 3 и так далее, пока не достигнете конца задачи. Это не относится к документации по коду. Код является нелинейным по своей природе, поэтому нельзя просто начать сверху и перейти к нижней части. Могут быть лучшие практики, дополнительные методы, списки параметров, концептуальные объяснения в сочетании с другими деталями и многое другое. Стратегия документирования кода состоит в том, чтобы представить полный пример кода, за которым следуют разделы, которые объясняют различные аспекты кода. Такой подход очень отличается от процедурного подхода, обычно применяемого в технических документах. -- **Понимание кода требует определения технического уровня вашей аудитории.** Технический писатель должен писать в соответствии с уровнем знаний своей аудитории, даже если технические уровни разных аудиторий сильно различаются. Документация обычно либо переписывается для продвинутых разработчиков, объясняя очевидное, либо отталкивает менее опытных разработчиков, поясняя слишком много. Реализация прогрессивных моделей раскрытия информации может быть сложной. Даже если аудитория технически грамотная, она не гарантирует, что у нее есть опыт в конкретной технологии, которая документируется. В результате, мы, технические писатели, часто представляем себя аудиторией. -- **Правильное форматирование кода и обращение к различным строкам также является проблемой.** Хочется применить подсветку синтаксиса кода, основанную на языке кода и хорошее форматирование кода для этого языка, которое следует стандартным соглашениям на этом языке. Если есть 50-100 строк кода, ссылки на различные аспекты кода также могут быть сложными - можно попробовать ссылаться на номера строк, если они есть в примерах, но у такого подхода есть свои проблемы. Вы переносите код или позволяете пользователю прокручивать по горизонтали? Сколько кода со встроенными комментариями, написанными для опытного программиста, а не систематического программиста, который начинает с первой страницы? -- **Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки.** Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Некоторый код может просто выполняться достаточно легко, а какой-то может потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения. -- **У инженеров гораздо лучше наметан глаз на хороший и плохой код.** Можно даже не осознавать, что ваш код плохой. Помните, что инженеры живут и дышат кодом, и многие считают, что код - это поэзия. Эффективная техника в коде (например, рекурсивные циклы, которые расширяют ресурсы по мере необходимости) может быть прекрасной, вызывая эстетику в уме инженера. Маловероятно, что технический писатель будет подходить к коду с таким же почтением и благоговением. Более приземленный подход к коду может затруднить учет того же отношения и точки зрения, которые пользователи имеют к этой теме. - -Вот некоторые из проблем, связанных с документированием кода. В разделах этого модуля будет рассказано о каждой из этих проблем более подробно. Хоть тема может показаться пугающей, но если примеры кода являются наиболее важным элементом хорошей документации по API, мы должны углубиться в это. - - - - [🔙](README.md) [Go next ➡](doc-research.md)