структура раздела

doc-code/doc-code.md

@@ -1,9 +1,48 @@
 # Почему так трудно документировать код?
 
-[Проблемы документирования когда](#problems)
 
 
-Если спросить у разработчиков, что является наиболее важным элементом документации API, то ответ будет один и тот же - это примеры кода. Примеры рабочего кода, которые разработчики могут легко скопировать и вставить в свою документацию должны включаться в API. Примеры кода, которые демонстрируют, как включить абстракции в реальную реализацию. Примеры кода, примеры приложений - что угодно. Много кода не бывает.
+Код программы, написанный на Java, C ++ или любом другом языке, сложно документировать в частности потому, что технические писатели часто не владеют языком программирования. Но даже для писателей или разработчиков, свободно владеющих языком, эта задача может быть трудной. Отсутствует пошаговый процесс, которому надо следовать. Код часто упорядочен в нелинейном порядке, поэтому не получится просто идти построчно по нему. Существует также вопрос о том, сколько документировать, что покрывать и куда включать документацию. В целом, лучшие практики документирования кода нечеткие и неопределенные, что делает документирование кода одной из самых сложных и трудоемких задач, стоящих перед техническими авторами.
+
+В разделе [Описание и образцы кода](conceptual-topics/code-samples.md) есть упоминание о важности документирования кода. Но, учитывая важность этой темы, мы рассмотрим ее шире в этом разделе.
+
+**Содержание раздела**
+
+
+[Свежий опыт документирования кода](#recent-experience)
+
+[Проблема 1: Код не следует пошаговой парадигме](#paradigm)
+
+[Проблема 2: Аудитория может иметь разный технический уровень](#variance)
+
+[Проблема 3: Код требует понимания конкретного языка программирования](#specific-language)
+
+[Проблема 4: Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки](#maintenance)
+
+[Проблема 5: У инженеров гораздо лучше наметан глаз на хороший и плохой код](#good-bad)
+
+[Важность документирования кода](#importance)
+
+<a name="recent-experience"></a>
+## Свежий опыт документирования кода(#)
+
+<a name="paradigm"></a>
+## Проблема 1: Код не следует пошаговой парадигме
+
+<a name="variance"></a>
+## Проблема 2: Аудитория может иметь разный технический уровень
+
+<a name="specific-language"></a>
+## Проблема 3: Код требует понимания конкретного языка программирования
+
+<a name="maintenance"></a>
+## Проблема 4: Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки
+
+<a name="good-bad"></a>
+## Проблема 5: У инженеров гораздо лучше наметан глаз на хороший и плохой код
+
+<a name="importance"></a>
+## Важность документирования кода
 
 
 Ниже видео инженера Рути Бен Дор на конференции «Write the Docs». На вопрос: «Каковы три наиболее важных элемента создания документации API?», Рут ответил (на 4:15):
@@ -16,7 +55,7 @@
 
 Несмотря на важность примеров кода, их нелегко реализовать. По этой причине они часто игнорируются или отсутствуют в документации API. На самом деле, примеры кода могут быть самой сложной частью документации, которую должны документировать технические писатели. В этом разделе разберемся, почему документирование кода может быть сложной задачей, а затем в дополнительных темах рассмотрим конкретные стратегии для успешного включения примеров кода в документацию.
 
-<a name="problems"></a>
+
 ## Проблемы документирования когда
 
 Рассмотрим несколько причин, почему документирование кода это сложная задача
@@ -25,7 +64,14 @@
 - **Код не следует пошаговой парадигме.** Основная парадигма, которой следуют большинство технических писателей, - это модель, основанная на задачах, где вы начинаете с шагов 1, 2, 3 и так далее, пока не достигнете конца задачи. Это не относится к документации по коду. Код является нелинейным по своей природе, поэтому нельзя просто начать сверху и перейти к нижней части. Могут быть лучшие практики, дополнительные методы, списки параметров, концептуальные объяснения в сочетании с другими деталями и многое другое. Стратегия документирования кода состоит в том, чтобы представить полный пример кода, за которым следуют разделы, которые объясняют различные аспекты кода. Такой подход очень отличается от процедурного подхода, обычно применяемого в технических документах.
 - **Понимание кода требует определения технического уровня вашей аудитории.** Технический писатель  должен писать в соответствии с уровнем знаний своей аудитории, даже если технические уровни разных аудиторий сильно различаются. Документация обычно либо переписывается для продвинутых разработчиков, объясняя очевидное, либо отталкивает менее опытных разработчиков, поясняя слишком много. Реализация прогрессивных моделей раскрытия информации может быть сложной. Даже если аудитория технически грамотная, она не гарантирует, что у нее есть опыт в конкретной технологии, которая документируется. В результате, мы, технические писатели, часто представляем себя аудиторией.
 - **Правильное форматирование кода и обращение к различным строкам также является проблемой.** Хочется применить подсветку синтаксиса кода, основанную на языке кода и хорошее форматирование кода для этого языка, которое следует стандартным соглашениям на этом языке. Если есть 50-100 строк кода, ссылки на различные аспекты кода также могут быть сложными - можно попробовать ссылаться на номера строк, если они есть в примерах, но у такого подхода есть свои проблемы. Вы переносите код или позволяете пользователю прокручивать по горизонтали? Сколько кода со встроенными комментариями, написанными для опытного программиста, а не систематического программиста, который начинает с первой страницы?
-- **Отслеживание работы примеров кода от релиза к релизу потребует работы контроля качества и обслуживания.** Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Некоторый код может просто выполняться достаточно легко, а какой-то может потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения.
+- **Отслеживание работы примеров кода от релиза к релизу потребует большой поддержки.** Если есть примеры кода, перенесенные в документацию, а не извлеченные из центрального репозитория, может быть сложно даже определить весь код, который нужно протестировать и поддерживать. Проверяется ли это с каждым выпуском? Насколько тестируемым будет код? Некоторый код может просто выполняться достаточно легко, а какой-то может потребовать создания примеров приложений или установки других технических сред, для работы. И возможно, придется добавить контекстный код, чтобы код мог реально работать, возможно, даже создавая пример данных или другую информацию, чтобы можно было вернуть правильные значения.
 - **У инженеров гораздо лучше наметан глаз на хороший и плохой код.** Можно даже не осознавать, что ваш код плохой. Помните, что инженеры живут и дышат кодом, и многие считают, что код - это поэзия. Эффективная техника в коде (например, рекурсивные циклы, которые расширяют ресурсы по мере необходимости) может быть прекрасной, вызывая эстетику в уме инженера. Маловероятно, что технический писатель будет подходить к коду с таким же почтением и благоговением. Более приземленный подход к коду может затруднить учет того же отношения и точки зрения, которые пользователи имеют к этой теме.
 
 Вот некоторые из проблем, связанных с документированием кода. В разделах этого модуля будет рассказано о каждой из этих проблем более подробно. Хоть тема может показаться пугающей, но если примеры кода являются наиболее важным элементом хорошей документации по API, мы должны углубиться в это.
+
+
+
+
+[🔙](README.md)
+
+[Go next ➡](doc-research.md)