Последние пять лет мы (documentat.io) занимаемся заказной разработкой документации для российских IT-компаний.
Разговор с почти каждым из наших клиентов начинается с фразы «нам нужно всё задокументировать, помогите нам в этом».
Наш опыт показывает, что разные компании понимают под этой формулировкой довольно разные вещи, и «всё» в разных компаниях тоже отличается.
В нашей практике такого рода просьбы сводятся к пяти направлениям работы:
- Описание требований к уже существующей системе (реверс-инжениринг требований).
- Создание пользовательской документации.
- Создание архитектурной документации, адресованной исключительно разработчикам.
- Создание API-документации (причем обычно речь идет о вводных и обучающих статьях (howtos/tutorials), а не к непосредственному написанию аннотаций к методам или правке Сваггера).
- Комментарии в коде (в стиле Javadoc или в свободном формате).
В этом докладе мы обсудим, что общего у этих направлений и чем они отличаются, и что делать, если вам нужно решить одну из подобных задач.
Этот доклад адресован в первую очередь тем, для кого написание документации НЕ является основной рабочей активностью: разработчикам, менеджерам и тимлидам.