Публикация научных статей.
Вход на сайт
E-mail:
Пароль:
Запомнить
Регистрация/
Забыли пароль?
Международный научно-исследовательский журнал публикации ВАК
Научные направления
Поделиться:
Разделы: Информационные технологии, Менеджмент, Управление и организация
Размещена 05.05.2016. Последняя правка: 07.05.2016.

Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному обеспечению

Фокина Татьяна Владимировна

нет

Новосибирский Государственный Университет

студент

Факторович Семен Борисович, руководитель отдела аналитики и технической документации, HDSoft


Аннотация:
Данная статья посвящена исследованию в области технической документации при разработке программного обеспечения. Проведенное исследование выявило определенный набор метрик измерения качества технической документации и позволило разработать набор рекомендаций по созданию технической документации.


Abstract:
The paper contemplates research in technical documentation in software development. Undertaken study revealed a specific set of quality metrics for technical documentation and made it possible to develop certain recommendations for creating technical documentation.


Ключевые слова:
техническая документация; спецификация требований; разработка программного обеспечения; управление проектами; техническое задание; формулировка требований; качество документации; метрики качества.

Keywords:
technical documentation; requirement specification; software development; project management; specification; formulation of requirements; quality of documentation; quality metrics.


УДК 004.91

Введение

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

Актуальность

Техническая документация имеет важное значение в разработке программного обеспечения. Качество формулировки технического задания и требований напрямую влияет на качество продукта; некорректно выбранная методика ведения документации и недостаточно качественное составление спецификации[1] может привести к ошибкам при разработке, частым переделкам, и в конечном итоге увеличит стоимость проекта, что является серьезным риском как в разработке программного обеспечения, так и среди любых проектов в сфере производства каких-либо товаров или услуг.

Цель

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

Задачи

1. Создать набор метрик качества технической документации на основе описанных в литературе и исходя из опыта проекта.
2. Выбрать наиболее эффективные из полученных метрик для конкретного проекта.
3. Разработать набор рекомендаций для организации документационных процессов в проекте путем тестирования и исследования выбранных метрик оценки качества технической документации. 

Научная новизна

В данном исследовании рассматривались метрики качества технической документации, взятые из [2], а также разработанные самостоятельно исходя из опыта команды разработки.

Результаты

Примеры метрик:

1. Количество открытий документа на чтение.

Метод измерения: количество открытий документа в день, за итерацию разработки проекта, на протяжении всей разработки.

Показывает, насколько члены команды разработки следят за документацией и фактом соответствия разработки документации.

2. Количество изменений документа.

Данная метрика подразделяется на два вида: редактирование и добавление данных.

Инструмент для измерения метрики: история изменений в документе.

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

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

Если после каких-либо изменений в документе повышается количество открытий для чтения, в команде эффективно работает система оповещений об изменениях в документации.

Пример: если документ хранится в Google Docs, имеется возможность воспользоваться встроенной историей изменений. Данный инструмент выделяет части, которые изменились в документе по сравнению с предыдущей версией, автора изменений и время изменения. Кроме того, есть возможность возврата к одной из предыдущих версий документа.

3. Реакция документации на изменения требований заказчика

Показывает реакцию команды разработки в целом и отдела документации в частности на изменения требований заказчика. Изменение отражается в документации, документация отражается в разработке.

Данная метрика тесно связана с предыдущей.

Метод измерения: количество выполненных запросов с изменениями требований от заказчика.

Изменения в документе, пришедшие извне команды разработки и отражающие новые требования заказчика предлагается помечать специальными маркерами, о виде которых необходимо договориться внутри команды (например: заказчик выдвинул новое требование, аналитик зафиксировал его в спецификации, пометил комментарием “TODO:заказчик”, разработчик по данному комментарию в кратчайшие сроки нашел новое изменение и приступил к работе)

4. Читаемость страницы

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

Метод измерения: количество времени, проведенного читателем на каждой странице.

5. Простота идентификации автора документации и связи с ним

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

Метод измерения: существование указания авторства, контактов автора.

6. Субъективная оценка качества документа читателем

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

Метод измерения: рейтинг каждой страницы; рейтинг каждого документа; система опросов команды.

7. Количество и происхождение читателей документа

Показывает актуальность документа; вовлеченность в процесс разработки членов команды из разных отделов (после измерения данного параметра становится возможным сделать вывод о виде занятости данных сотрудников (полная/частичная) или отделов в целом); систему работы руководителя с подчиненными (есть вероятность, что только руководитель команды читает документ и впоследствии ставит задачи на основании прочитанного).

Метод измерения: количество читателей документа в целом; количество читателей из каждого отдела; количество руководителей на всех работников отдела.

8. Удобство доступа (хранение)

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

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

9. Уточнения терминов.

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

Метод измерения: количество уточнений терминов посредством вопросов, задаваемых автору документа.

10. Частота обращений к глоссарию (если есть)

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

Метод измерения: количество обращений к документу с глоссарием.

11. Смысловые вопросы по документу, задаваемые автору.

Позволяет понять, что в документе в целом нужно что-то доработать.

Метод измерения: наличие и количество вопросов по документу.

12. Уровень читаемости.

Показывает восприятие логики документа в целом каждым членом команды. Может указывать на то, что документ не достигает поставленной цели, либо цель документа сформулирована неточно.

Метод измерения: опросы команды.

13. Время чтения всего документа

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

Метод измерения: количество времени, затраченного на чтение всего документа; сравнение статистики по разделам и по всему документу.

14. Лексический уровень

Позволяет определить лексический уровень автора и предпринять меры по его повышению.

Метод измерения: количество повторений терминов в тексте, количество повторяющихся требований/задач (дублируемость)

15. Грамматический уровень

Позволяет проверить автора на владение языком и установить необходимость повышения этого уровня.

Данная и предыдущая метрики необходимы для повышения уровня читаемости документа, т.к. в первую очередь читатель обращает внимание не на смысл, а на оформление (если есть какие-то недочеты, на них ставится акцент).

Метод измерения: количество грамматических/пунктуационных ошибок на страницу в определенной версии документа. 

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

Теоретическая часть исследования заключалась в изучении и выборе оптимальных метрик, подходящих для методологии разработки проекта[3][4]. В практической части исследования была протестирована эффективность выбранных метрик и влияние на качество документации.

Исследование проводилось в рамках проекта, сочетающего в себе методологии разработки Kanban и RUP. Подробнее о проекте можно узнать по ссылке statium.ru.

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

Примеры рекомендаций:

1. Вычитывать документ на орфографическую и фактологическую корректность.

2. Поддерживать актуальность документации.

3. Организовать удобную для команды систему хранения документации.

4. Организовать удобную для команды систему навигации по документу.

5. Указывать авторство: указывать, от какого заказчика пришло конкретное требование.

6. Указывать автора документа и людей, вносивших изменения.

7. Регулярно опрашивать команду разработки о качестве документации.

8. Регулярно вносить изменения с учетом пожеланий команды.

9. Вести историю изменений.

10. Изменять документ в определенное время.

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

Приведем пример. В проекте, в рамках которого проводилось исследование, была некорректно организована система хранения документации. Чтобы объяснить суть проблемы, дадим краткую вводную в предметную область проекта.

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

Для измерения актуальности данной проблемы была использована метрика №5 “Простота идентификации автора документации и связи с ним” и метрика №8 “Удобство доступа”. Проблема оказалась не только насущной, но и критически важной. Были предприняты следующие шаги:

1. Добавлены в спецификацию ссылки на разрозненные документы.

2. Добавлено указание автора в каждый документ.

3. Сформирован общий для всей команды Google Диск, в котором хранится документация.

4. Расформирован отдел документации. Ответственным за документооборот назначен один человек.

5. Принято решение об отказе от создания техническим писателем отдельных документов для каждого добавляемого метода. Разработчики находят и изучают информацию о методах в математических источниках самостоятельно.

На внедрении каждого шага были протестированы метрики №5 и №8 и наблюдалось значительное улучшение показателей удобства хранения.

Заключение

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

Библиографический список:

1. Gothelf J., Seiden J., Lean UX [Text] / Jeff Gothelf, Josh Seiden // O’Reilly, the Lean series. - 2013 – 130.
2. Howard T., Contemporary TechDocs [Text] / Troy Howard // blog, paper / Portland, 13.08.2015.
3. Rubin K.S., Essential Scrum: A Practical Guide to the Most Popular Agile Process [Text] / Kenneth S. Rubin // Addison-Wesley. - Michigan, 2012 - 453.
4. Kniberg H., Lean from the Trenches: Managing Large-Scale Projects with Kanban [Text] / Henrik Kniberg // Pragmatic Bookshelf. - 2011 - 157.




Рецензии:

5.05.2016, 17:10 Эрштейн Леонид Борисович
Рецензия: Это не статья, а какой-то конспект не известно чего. Публиковать такое нельзя.

5.05.2016, 17:55 Луговая Виктория Николаевна
Рецензия: текст похож на отчет по практике, но не статью. не рекомендуется к печати.

5.05.2016, 20:55 Лещенко Василий Васильевич
Рецензия: Текст даже не похож на научную статью. Не рекомендую к печати.

6.05.2016, 8:07 Феофанов Александр Николаевич
Рецензия: Рецензия на статью Фокиной Т. В. «Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному продукту» Статья «Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному продукту» Фокиной Т. В. посвящена исследованию в области технической документации при разработке программного обеспечения. Автором проведен анализ метрик качества технической документации, приведен перечень рекомендаций, которые следует учитывать менеджеру при написании технической документации и мониторингу текущего качества проектной документации. В статье приведен пример внедрения одной из рассматриваемых метрик, сделан вывод об эффективном ее применении. В настоящей статье Фокиной Т. В. используется информация из открытых источников, не содержатся сведения ограниченного характера.Рекомендуется отправить статью автору на доработку с целью соблюдения требований, предъявляемых к подобным работам. Замечание руководителю. Следует применять научный стиль речи при изложении основной части статьи. Необходимо сформулировать определение терминов «качество», «критерий качества» рассматриваемых в статье, привести перечень рисков, на которые ссылается автор. Статья «Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному продукту» Фокиной Т. В. может быть рекомендована к публикации после ее доработки. Д.т.н., профессор Феофанов А.Н.

6.05.2016, 11:45 Попова Галина Валентиновна
Рецензия: Статья "Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному обеспечению" НЕ РЕКОМЕНДУЕТСЯ К ПУБЛИКАЦИИ. Статья не идентифицируется как научная.



Комментарии пользователей:

5.05.2016, 17:42 Бондаревский Аркадий Самуилович
Отзыв: Руководителю работы: Критерий качества и "требования", - не синонимы (первое, - часть, не может отождествляться со вторым, - целым). Ибо "требования" есть императив "критерия качества". Заголовок следует скорректировать, а работу привести в соответствие. Бондаревский Аркадий Самуилович.


5.05.2016, 19:15 Фокина Татьяна Владимировна
Отзыв: Аркадию Самуиловичу: здесь не подразумевается, что это синонимы. Наверное, стоит разделить, что отслеживаемое качество относится именно к документации, а требования [спецификация требований] - отдельный документ, определяющий требования к разрабатываемому программному обеспечению. И спасибо вам за отзыв, я учла нечеткость формулировки и исправила название. Фокина Татьяна


5.05.2016, 21:46 Бондаревский Аркадий Самуилович
Отзыв: Татьяна Владимировна, вчитайтесь в название своей работы: "Формулировка и анализ критериев качества технической документации на примере спецификации требований к программному обеспечению". - "Критерии" не могут анализироваться посредством "требований" , которые, как всякие "требования" в себя "критерии" включают. Это я и хотел сказать Вашему руководителю и Вам. На будущее. Следите за речью. Например, в Вашей реплике два раза подряд идут "требования". Это тоже не здорово, - плеоназм. А так, - больше вопросов нет. Удачи Вам. Б.


Оставить комментарий


 
 

Вверх