Вернуться назад

Зачем пишут документацию на ПО?

Что такое документация на программное обеспечение?

Документация содержит данные, необходимые для разработки, производства, эксплуатации и сопровождения ПО. 

Это насущная тема, поскольку в ней пересекаются два практических момента. Писать проектную и техническую документацию к коду очень важно. При этом программисты зачастую не любят этим заниматься, потому что это трудоемкий процесс. Одна из распространенных ситуаций – написание документации откладывается до последнего, потому что разработчик едва успевает писать тесты к коду.

Интересный момент – документация должна быть достаточной и не избыточной. Когда документация избыточна, с ней будет сложно работать в дальнейшем.

Если технической документации к коду нет, то его трудно читать и сложно сопровождать, а другим программистам проблематично работать с ним. Через некоторое время и сам автор кода будет разбираться в нем с трудом, если ленился писать документацию.

Замечено: если код документируется, то структура и логика улучшаются. Код, который написан просто и ясно, называют читаемым и даже самодокументируемым. 

Типы документации

Документация на ПО бывает четырех типов:

1. Проектная / Архитектурная: дает обзор ПО, описывает рабочую среду и принципы разработки, объясняет архитектуру и паттерны, предлагает идеи по улучшению кода в будущем, предоставляет правила и стайлгайд для единообразной работы с кодом.

2. Техническая: в комментариях к коду технически поясняет, что он делает и почему именно так.

3. Пользовательская: описывает, как использовать программу и какого результата можно ожидать от разных функций, предоставляет систему помощи.

4. Маркетинговая: рассказывает о функциях и рыночных преимуществах софта. 

 

 

Генераторы документации

Техническая документация зачастую создается из комментариев к коду. Она описывает структуру данных, интерфейсы, алгоритмы и API.

Существует множество программ для создания документации: Docz, Doxygen, Pandoc, Markdown, Document! X, Natural Docs, Sphinx, Epydoc, Javadoc, RDoc, JSDoc, Dr. Explain, NDoc, Ghostdoc, ROBOdoc, Latex и др. Генераторы документации ориентированы на конкретный язык или ряд языков. Например, для программ на языке Python используются Doxygen, Sphinx и Epydoc.

Упрощенно, программы-генераторы документации анализируют исходный код, а также извлекают комментарии к исходному коду и метаданные, затем компонуют их и создают документ. Он может быть представлен в одном из общепринятых форматов, например, в RTF, PDF или HTML.

Для каких случаев пишут документацию?

  1. Это нужно разработчику, если он будет использовать, обслуживать или менять свой код через полгода. Замечено, что для разработчика код, который он написал полгода назад, по сложности восприятия мало отличается от кода, написанного кем-то другим. 
  2. Документация нужна, если ожидается, что другие люди будут работать с ним или использовать его. 
  3. Документация понадобится, если разработчик хочет, чтобы контрибьюторы улучшали код. 
  4. Чтобы научиться грамотно писать документацию, нужна постоянная практика. Быть хорошим техническим писателем – ценный навык для программиста.
  5. Писать документацию нужно, чтобы поддерживать лучшие практики в компании.
  6. 4 типа документации на ПО нужны на разных этапах: проектная и техническая документация нужна самому программисту, его коллегам, тем, кто будет работать с кодом позднее, а также контрибьюторам и для опенсорс-распространения; пользовательская понадобится для обучения, а также службе саппорта, чтобы помогать в решении проблем; маркетинговая документация пригодится тем, кто рассказывает о рыночных преимуществах продукта в разных бизнесовых ситуациях.

Существуют гайды по написанию документации и даже глобальное сообщество Write the Docs («Пишите доки»). Это комьюнити разработчиков, которые увлечены темой. У него есть группа в Slack. На официальном сайте Write the Docs сообщает, что устраивает конференции на трех континентах и локальные митапы.

В общем, тема документации – обширная, можно заметить, что разработчики часто обсуждают ее и упоминают о проблеме отсутствия документации. Блог Almamat еще вернется к теме рекомендаций для написания документации. 

 

Изображение: Shutterstock / wacomca

Вернуться назад
Поделиться
Запишитесь на бесплатный диагностический урок
Читать еще