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

doc-code/doc-research.md

@@ -4,12 +4,64 @@
 
 Несколько академических статей выделяются как заслуживающие внимания:
 
-- **Когда не нужно комментировать: вопросы и компромиссы с документацией API для проектов C ++**
+- **Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++**
 
 В этой статье рассказывается, как разработчики из Google находят и используют документацию кода. Исследователи обнаружили, что простой код иногда разработчики предпочитают исследовать напрямую. Однако для более сложного кода разработчики обращаются к документации кода, часто просматривая формальные объявления классов для получения нужной информации. В других случаях они смотрят на комментарии в коде реализации. Помимо предоставления руководства по наилучшему расположению документации, исследователи также определяют, какой тип ответов и рекомендации разработчики хотят получить в документации.
 
-- **Как разработчики используют документацию API: исследование наблюдений**
+- **Как разработчики используют документацию API: изучение наблюдений**
 
 В этой статье исследователи смотрели на то, как разработчики взаимодействуют с документацией API, и обнаружили сочетание как систематического (сначала читайте, изучайте позже), так и оппортунистического (изучайте сначала, читайте позже) стилей обучения. Хотя мы часто пишем систематически, сосредоточение внимания на оппортунистическом поведении может быть более полезным, что побудит нас более внимательно следить за улучшением поиска, навигации, интерактивных компонентов, устранения неполадок, сообщений об ошибках и других функций, ориентированных на действия.
 
-Обе эти статьи взяты из научных журналов. На самом деле редко можно найти исследования о документации API в академических журналах (не знаю почему), и когда вы их находите, они часто бывают в инженерных журналах, или журналах по информатике (а не в журналах по техническим коммуникациям). 
+Обе эти статьи взяты из научных журналов. На самом деле редко можно найти исследования о документации API в академических журналах (не знаю почему), и когда вы их находите, они часто бывают в инженерных журналах, или журналах по информатике (а не в журналах по техническим коммуникациям).
+
+[Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++](#no-comments)
+
+- [Тип кода, которому нужна документация](#type-of-code)
+- [Когда документировать код](#time-to-document)
+- [Вопросы, решаемые в документации кода](#questions)
+- [Заключение](#conclusion-one)
+
+[Как разработчики используют документацию API: изучение наблюдений](#use-api-doc)
+
+- [Систематическое поведение против оппортунистического](#sys-versus-opp)
+- [Проектирование для оппортунистического поведения](#design)
+- [Временные затраты пользователей](#time)
+- [Заключение](#conclusion-two)
+
+[Выводы исследований](#takeaways)
+
+
+
+
+<a name="no-comments"></a>
+## Когда не нужно комментировать: вопросы и компромиссы документации API для проектов на C++
+
+<a name="type-of-code"></a>
+### Тип кода, которому нужна документация
+
+<a name="time-to-document"></a>
+### Когда документировать код
+
+<a name="questions"></a>
+### Вопросы, решаемые в документации кода
+
+<a name="conclusion-one"></a>
+### Заключение
+
+<a name="use-api-doc"></a>
+## Как разработчики используют документацию API: изучение наблюдений
+
+<a name="sys-versus-opp"></a>
+### Систематическое поведение против оппортунистического
+
+<a name="design"></a>
+### Проектирование для оппортунистического поведения
+
+<a name="time"></a>
+### Временные затраты пользователей
+
+<a name="conclusion-two"></a>
+### Заключение
+
+<a name="takeaways"></a>
+## Выводы исследований