ОСОБЕННОСТИ ДОКУМЕНТИРОВАНИЯ ДЛЯ РАЗРАБОТЧИКОВ

Процесс документирования для пользователей давно отлаженная система, но основной болью и по сей день остаётся процесс написания документации для разработчиков (программистов). Написание документа для программистов вводит в ступор и страх любого писателя, так как, на первый взгляд, это кажется, что-то запредельное и непонятное. И тут я собственно буду согласна, так как не каждый специалист сможет написать документ для отдела разработки, этим должен заниматься писатель, который имеет достаточные базовые знания по программированию и базам данных. Такие писатели, конечно, есть, но их не так много. Что же тогда делать, когда документ нужен, а программиста-писателя нет? В этой статье я решила рассказать об общих правилах, при написании документа для разработчиков, и о том, какие документы следует написать, чтобы новые и действующие программисты компании работали без проблем.

Общие правила

Ниже представлены, на мой взгляд, самые актуальные рекомендации при написании документации для программистов:

1) Для начала следует собрать все термины и определения к ним, которые используют разработчики.

2) Систематизировать собранные термины и составить глоссарий.

3) Погрузится в тему документа самостоятельно.

4) Собрать всю информацию у программистов, по создаваемому документу.

5) Документ должен быть написан на языке программистов, так как они не пользователи и им излишня беллетристика не нужна.

6) Документ лучше представлять в одностраничном виде, так как по наблюдениям данный вид представления для них самый удобный.

7) Документ должен быть написан лаконично.

8) В документе должна содержаться только основная концепция.

9) Документ должен быть оформлен согласно текущим стандартам компании, если такого стандарта нет, то если следует ввести. При создании данного стандарта необходимо учитывать пожелание программистов, ведь в первую очередь должно быть удобно им, а не вам.

10) Перед публикацией документ должен быть прорецензирован программистами.

11) Документ лучше отправлять на рецензирование частями, это повышает вероятность, что ваш документ, вообще, прочтут.

12) Документ должен подвергаться рецензии несколько раз, пока он, с точки зрения, отдела программные не будет идеальным.

13) Программисты, как правило, не любят читать документы, поэтому следует корректно напоминать о том, что вы ждёте от них документ.

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

Документация для разработчиков

Документация может быть разная: проектная и техническая.

Проектная документация

Основной проектной документацией является Техническое задание (ТЗ), которое является стартом при создании программы. ТЗ, как правило, написано по ГОСТу19 или по ГОСТу 34. Этот документ давать разработчику нет никакого смысла, вам его все равно вернут обратно с фразой: «Много букв!». ТЗ необходимо разбить на требования (комплекс задач), а требования на задачи, где в каждой из них чётко и ясно указано, что нужно сделать. По каждой задаче, должна вестись история ошибок. Для этого сейчас есть множество программ, позволяющих вести проект по разработке ПО. Например, Team Foundation Server (сокр. TFS). Есть и куда проще программы, так называемые багтрекинговые системы (системы отслеживания ошибок). Например, Atlassian JIRA, Mantis bug tracking system.

Как правило, в отделах разработке уже установлены такие программы. Если вы не знаете, есть ли у вас подобного рода программа в компании, то следует уточнить, так как из неё писатель может черпать множество информации как для документации программистам, так как для пользовательских инструкций. Далее, я советую, нарисовать структуру программы именно, с точки зрения, программирования с помощью UML-диаграммы. Сделать их лучше несколько. Общую (укрупнённая поверхностная диаграмма) надо сделать обязательно, а далее можно сделать диаграммы классов, компонентов, объектов и т. д. Но хотя бы одна диаграмма, где все показано, с точки зрения, программирования должна быть обязательно! Любому новенькому программисту будет легче и проще войти в процесс.

Техническая документация

К технической документации можно отнести схему базы данных и описание API.

Логическая и физическая схема базы данных должна быть обязательно. Для этого следует написать два ГОСТовских документа: «Инструкция по формированию и ведению базы данных» (ГОСТ 34, РД 50-34.698-90, п.5.12) и «Описание организации информационной базы» (ГОСТ 34, РД 50-34.698-90, п.5.5). Данные документы будут удобны как писателям, так и программистам. Главное помнить, что эти документы следует обновлять раз в неделю или две, чтобы они были актуальными постоянно.

При фразе «Описание API» хочется сразу спросить: «Это, вообще, что?». Поясняю, API — это набор готовых классов, функций, процедур, структур и констант. API технология обеспечивает взаимодействие модулей. Например, у вас есть кот Барсик, который любит лежать на обеденном столе. Вам это не нравится. Вы говорите Барсику: «Барсик, брысь со стола!». Барсик хоть и нехотя, но слезает со стола. Так вот, API — это набор команд, благодаря которым кот Барсик понял хозяина, что ему следует слезь со стола. Короче говоря, для программистов документ «Описание API» вещь дельная! О том, как сделать такой документ, это тема отдельной большой статьи, в данной статье я подробно не буду это рассматривать.

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

DocPlace 2018-11-06

Добавить комментарий