Дока — термин программирования и документирования¶
Дока — разговорный термин, обозначающий документацию к программному обеспечению, а также специалиста, занимающегося её созданием и поддержкой. В русскоязычном IT-сообществе слово является сокращением от «документация» и используется преимущественно в неформальном общении; в официальном контексте применяется термин «техническая документация».
¶Этимология и употребление
Слово «дока» сформировалось в русскоязычном профессиональном жаргоне программистов и системных администраторов в 1990-е — 2000-е годы. Оно образовано усечением слова «документация» по модели, типичной для компьютерного сленга (ср. «дев» от «разработчик», «релиз» от «релиз-менеджер»). В узком контексте под «докой» понимается текстовый материал, описывающий программный интерфейс, формат данных, протокол или порядок эксплуатации системы. В более широком — весь комплекс сопроводительных материалов к продукту.
Термин имеет два основных значения:
- Документация — тексты, схемы, примеры кода и справочные материалы, сопровождающие программный продукт.
- Документировщик — специалист, формализующий знания о системе и оформляющий их в виде, пригодном для использования разработчиками и пользователями.
¶Виды программной документации
Согласно стандарту IEEE 829 и его российскому аналогу ГОСТ 34.602-89, документация на программные средства подразделяется на несколько типов:
| Тип документа | Назначение |
|---|---|
| План тестирования | Описывает стратегию и объём тестирования |
| Спецификация тест-кейсов | Перечень и описание отдельных тестов |
| Отчёт о тестировании | Результаты выполнения тестов |
| Руководство пользователя | Инструкции по использованию продукта |
| Руководство администратора | Настройка и обслуживание системы |
| Техническое описание | Архитектура, API, форматы данных |
В отечественной практике также применяется система стандартов ЕСКД (Единая система конструкторской документации) и ГОСТ на программную документацию (серия 34), регламентирующая состав и оформление документов на программные комплексы для государственных и оборонных заказов.
¶Способы документирования
¶Документация в коде (docstrings)
Строки документации (docstrings) — литеральные строки, размещаемые в начале модуля, класса или функции и доступные программным способом во время выполнения. Механизм поддерживается во многих языках: Python (PEP 257), Java (Javadoc), C# (XML-комментарии), Rust (rustdoc), Go (godoc). Инструменты вроде Sphinx (Python) или Doxygen (C/C++) генерируют из них статические сайты и справочники.
¶README и сопроводительные файлы
В формате репозиториев Git стандартом де-факто является файл README (обычно README.md в разметке Markdown), содержащий краткое описание проекта, инструкции по установке и примеры использования. Вместе с ним часто размещаются LICENSE (лицензия), CONTRIBUTING (правила участия), CHANGELOG (история изменений) и CODE_OF_CONDUCT.
¶API-документация
Описание программных интерфейсов традиционно оформляется в форматах OpenAPI (Swagger), RAML или API Blueprint. Спецификация OpenAPI, основанная на YAML или JSON, позволяет автоматически генерировать интерактивную документацию и клиентские библиотеки.
¶Внутренняя и пользовательская документация
Внутренняя документация (internal docs) предназначена для команды разработки: архитектурные решения (ADR — Architecture Decision Records), описания процессов, онбординг-материалы. Пользовательская документация ориентирована на конечного потребителя и включает руководства, справочные статьи, базы знаний.
¶Роль документации в разработке
Качественная документация снижает стоимость ввода новых сотрудников в проект, упрощает сопровождение и повышает надёжность интеграций. Согласно исследованиям в области программной инженерии, недостаток документации — одна из основных причин «вырождения» легаси-систем, когда поведение программы становится непонятным даже её авторам.
В agile-разработке документация традиционно считается второстепенной по сравнению с работающим кодом, однако практики DevOps и «documentation as code» (ведение документации в системе контроля версий наравне с кодом) вернули ей значение. Инструменты вроде Docusaurus, MkDocs, Jekyll и GitBook позволяют хранить и версионировать документацию совместно с исходным кодом.
¶Специальность «документировщик»
В крупных технологических компаниях роль технического писателя (technical writer) выделена в отдельную специальность. В России и СНГ такие специалисты работают в IT-компаниях, телекоммуникациях и на производстве, создавая руководства, API-документацию и справочные материалы. Смежной областью является UX-писание (UX writing) — создание текстов для интерфейсов: подсказок, сообщений об ошибках, онбординг-текстов.
В open source проектах документирование традиционно возлагается на самих разработчиков, что нередко приводит к её дефициту. Для стимулирования участия в документировании существуют специальные инициативы, например Hacktoberfest с отдельными метками для задач по документации.
¶Примечания
Термин «дока» не имеет закреплённого значения в формальных стандартах и используется преимущественно в устной и неформальной письменной речи инженерного сообщества.
¶Источники
- IEEE Std 829-2008. Standard for Software and System Test Documentation
- ГОСТ 34.602-89. Информационные технологии. Автоматизированные системы. Состав и порядок документации при создании автоматизированных систем
- PEP 257 — Docstring Conventions (Python Software Foundation)
- OpenAPI Specification 3.1.0
- Гибсон Д., Свэнсон Дж. «Документирование программного обеспечения» (The Documentation of Software)