Пять значений фразы «Нам нужно всё задокументировать»

Последние пять лет спикер занимается заказной разработкой документации для российских IT-компаний. Разговор почти с каждым клиентом начинается с фразы: «Нам нужно всё задокументировать, помогите нам в этом».

Опыт показывает, что разные компании понимают под этой формулировкой довольно разные вещи, и «всё» в разных компаниях тоже отличается. В практике команды спикера эти просьбы сводятся к пяти направлениям работы:

• Описание требований к уже существующей системе — реверс-инжиниринг требований.
• Создание пользовательской документации.
• Создание архитектурной документации, адресованной исключительно разработчикам.
• Создание API-документации — причем обычно речь идет о вводных и обучающих статьях (howtos/tutorials), а не к непосредственному написанию аннотаций к методам.
• Комментарии в коде — в стиле Javadoc или в свободном формате.

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