Вступление
В этой статье расскажу о том, зачем вообще заниматься документированием, что на проекте по автоматизации может документироваться, скажу несколько слов о правилах ведения документации, покажу свою практику документирования кода. А в заключение приведу пример того, что описанные мной правила подтверждаются опытом других коллег.
Зачем вообще документировать
В общем и целом, документация помогает разобраться. Разобраться в том, что вообще планировалось от системы, как она устроена и как развивается. К примеру, в команду разработки попадает новый человек. Ему нужно сориентироваться. В том числе сориентироваться в том, как устроена система, которую ему предстоит дорабатывать. И желательно, чтобы ему хватило одного часа для понимания назначения системы и общей схемы работы. В дальнейшем, в процессе разработки, программисту требуется понять, по каким правилам ведётся разработка, как устроен конвейер по производству софта, какие приняты соглашения по написанию кода. Опять же сверху вниз: сначала общая, понятная схема, далее можно спуститься до конкретных инструкций.
Что может документироваться
Вот небольшой список того, что может документироваться:
• Требования к программному обеспечению;
• Архитектура системы, пользовательский и программный (API) интерфейсы;
• Правила написания кода: соглашения, регламенты, инструкции;
• Правила тестирования кода: модульное, функциональное и интеграционное;
• Правила управления проектом: методики, системы, подходы;
• DevOps практика: изменение, обновление и в целом управление версиями;
• Техническая документация: руководства пользователя, инструкции по эксплуатации для сопровождения.
Основные правила ведения документации
В практике выработались следующие подходы по правилам ведения документации:
1. Определена цель документации. Человеку должно быть ясно, желательно из названия, какие именно знания он получит.
2. Понятная документация. Документация должна быть понятной. Все искусство в том, чтобы сложные вещи постараться изложить простым понятным языком. Если используются различные термины, то их нужно сопроводить глоссарием.
3. Документация должна быть по делу. Лишним инструкцию лучше не перегружать. Приведу пример. Мы внедряем в несколько конфигураций одну и ту же подсистему, допустим, реализующую интеграционные механизмы. Инструкцию нужно описывать по шагам: делай раз, делай два, делай три – и получишь такой-то результат.
4. Атомарность документации. Этого пункта касался, когда описывал функциональные тесты. Нужно писать инструкцию, определив конкретную цель, и стараться не выходить за рамки решения задач для достижения этой цели. Тем самым инструкция должна быть максимально атомарна. Не зависимая от других. Такую инструкцию легче поддерживать, а самое главное, читать. Удобно потреблять информацию небольшими, но цельными, законченными блоками. Так она проще усваивается.
5. Жизненный цикл документации. Желательно, чтобы работа с документацией была прописана в регламенте разработки. Например, мы изменили кодовую базу, покрыли систему тестами, а после обновили сопроводительную техническую и пользовательскую документацию. В таком случае документация будет живая. Иначе она через некоторое время протухнет и потеряет актуальность. Иногда даже будет вредить.
6. Количество документации. Все документировать бессмысленно. Это занимает много времени при создании таких документов и после потребует времени на поддержку и изменение. Да бывает много документации, и в моей практике такое случалось. При внедрении «Комплексной автоматизации» был потрачен вагон времени на пользовательские инструкции, а их банально использовали только на 10%.
Документирование кода
Идеальная ситуация, когда комментируются только процедуры и функции (то, что написано над ними). Это удобно, потому что IDE использует эти данные и даёт подсказки при их вызове. А вот сам код желательно избавить от комментариев. Код желательно писать так, чтобы из него было понятно, что он делает, и комментарии не требовались. Это решается разными способами. Например, осмысленным и лаконичным названием переменных. Имена функциям давать нужно так, чтобы из прочтения было понятно, что она делает и что вернёт. Был проект, когда писал биллинговую систему. Там были достаточно серьёзные алгоритмы расчёта стоимости. Сначала мы с командой описывали всё комментариями в коде, что и как работает. Потом поняли, что собрать это воедино и понять, как в целом все работает, будет очень сложно. И вынесли всё техническое описание в базу знаний.
Опыт коллег
На прошедшем Инфостарте интересовался темой функционального тестирования и ходил по докладам этой тематики. В докладе Андрея Хашкина увидел, что коллеги сначала занялись функциональным тестированием и по ходу зацепили тему пользовательских инструкций. Это получилось естественно. Инструкции у них логичным образом вытекли из самих тестов, тесты автоматически создавали инструкции. Обновляли тесты и сразу за ними пользовательские инструкции. Поддерживая их тем самым в актуальном состоянии. То есть, они просто подтвердили на практике выше описанные мной правила.
Заключение
В целом документирование полезная штука. Если оставить продукт без документации, то после могут возникнуть трудности. Проходил это неоднократно. Тут надо знать меру, много тоже плохо. Если вписать работу с документацией в регламент разработки, сделав это обязательным пунктом, и проводить такое же ревью, как и у кода, то документация будет развиваться естественно и находиться в актуальном состоянии.
Успехов! ;)
Мои публикации и контакты
Ссылки
Об устройстве функционального тестирования в 1С
https://dzen.ru/a/ZSvwcrqcv2E09_RX
Опыт применения Vanessa-Automation и других инструментов для обучения, ролевой модели и тестирования
https://event.infostart.ru/2023/agenda/1931942/
