Рубрика «документирование кода»

Меня зовут Андрей Поляков, я руководитель группы документирования API и SDK в Яндексе. Сегодня я хотел бы поделиться с вами докладом, который я и моя коллега, старший разработчик документации Юлия Пивоварова, прочитали несколько недель назад на шестом Гипербатоне.

Светлана Каюшина, руководитель отдела документирования и локализации:
— Объемы программного кода в мире в последние годы сильно выросли, продолжают расти, и это влияет на работу технических писателей, которым приходит все больше задач на разработку программной документации и документирования кода. Мы не могли обойти стороной эту тему, посвятили ей целую секцию. Это три взаимосвязанных доклада, посвященных унификации разработки программной документации. Я приглашаю наших специалистов по документированию программных интерфейсов и библиотек Андрея Полякова и Юлию Пивоварову. Передаю им слово.Читать полностью »

Ворочаем большими объёмами документации - 1

  • А как вы поддерживаете справку по API в актуальном состоянии?
  • Как можно организовать и хранить локализованные версии?
  • Вы проверяете текст на наличие недопустимых символов и на валидность разметки?
  • Как организовать проверку (вычитку) топиков?

Эти и другие вопросы я часто слышу от технических писателей на конференциях. Для небольших объёмов документации достаточно вручную пересмотреть документы и обновить/подставить/поправить всё, что нужно. А если объёмы документации выросли?

Наша документация выросла до более чем 154 000 документов только по .NET-линейке продуктов, из них около 140 000 документов — это справка по API. Около 8-10 тысяч топиков добавляются каждый мажорный релиз (т.е. дважды в год). В этой статье я расскажу как мы справляемся с такими объёмами.

Здесь я не приведу названия общедоступных инструментов, потому что всё, что мы используем — это самописные приложения и сервисы, которые глубоко интегрированы в нашу инфраструктуру и слабо применимы вне её. Поэтому в этом хабратопике я поделюсь техническими решениями, а не инструментами.

Читать полностью »

Вчера произошло достаточно значимое событие на рынке разработки. Точнее в сфере поддержки и сопровождении программных продуктов. StackOverflow запустил раздел документация. Почему это важно?

Читать полностью »

Оформление документации в Doxygen - 1

Недавно мной была написана статья, посвященная системе документации Doxygen (если вы не знакомы с данной системой, то советую обратить внимание на указанную статью и познакомиться с ней хотя бы в общих чертах). В комментариях к ней был поднят важный вопрос об оформлении документации в Doxygen, и этот вопрос актуален, поскольку зачастую используется стандартное оформление, которое хоть и практичное, но достаточно невзрачное.

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

Документируем код эффективно при помощи Doxygen - 1

Данная статья представляет собой введение в систему документирования исходных текстов Doxygen, которая на сегодняшний день, по имеющему основания заявлению разработчиков, стала фактически стандартом для документирования программного обеспечения, написанного на языке C++, а также получила пусть и менее широкое распространение и среди ряда других языков.

В этой статье мы сначала познакомимся с самой системой и её возможностями, затем разберёмся с её установкой и базовыми принципами работы, и, наконец, завершим знакомство рассмотрением различных примеров документации, примеров того, как следует документировать те или иные части кода. Словом, познакомимся со всем тем, что позволит вам освоится и начать работать с этой замечательной системой.
Читать полностью »


https://ajax.googleapis.com/ajax/libs/jquery/3.4.1/jquery.min.js