...

Глава 8. Документирование решений

Тема в разделе "Краткое руководство по созданию Low-code решений", создана пользователем ELMA365, 4 май 2023.

  1. ELMA365

    ELMA365 Moderator

    Ключевые потребители документации решения:
    • Пользователи решения;
    • Сотрудники поддержки, которые помогают пользователям работать с решением;
    • Администраторы, которые обеспечивают его доступность;
    • Разработчики, которые его создали и развивают.
    У каждого потребителя документации свои запросы. Например:
    • Пользователям решения важно понять, как им взаимодействовать с системой. При этом важно помнить, что под пользователями скрываются сотрудники разных ролей. Для каждой роли необходима своя документация;
    • Сотрудникам поддержки решения важно быстро ориентироваться при обращении пользователей и уметь вносить изменения в само решение или в данные в нем;
    • Администраторам решения нужно контролировать работоспособность и уметь её восстанавливать в случае внештатных ситуаций;
    • Разработчикам необходимо сохранить знания о решении и избежать потери информации при уходе одного из участников команды.
    Кроме этого, при документировании решения необходимо опираться на уровень пользователей, которые будут с ним работать. Например, решение для пользователей с низким уровнем компьютерной грамотности, потребует описания детальных пошаговых инструкций.

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

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

    Перечень документов, которые могут быть сформированы по решению:
    1. Краткое описание решения: для чего оно и какие задачи решает. Такое описание поможет любому потребителю быстро понять суть решения;
    2. Настройка решения: как правильно настроить решение в начале и на что влияют эти настройки;
    3. Описание инфраструктуры: какие мощности используются для решения, как контролировать его доступность и обслуживать сервера;
    4. Инструкции по ролям — описание интерфейсов и сценариев взаимодействия с решением для каждой роли;
    5. Архитектура решения:
    a. Состав решения — что в себя включает решение;
    b. Взаимодействие элементов решения — как они взаимодействуют между собой;
    c. Возможности расширения решения — как правильно использовать заложенные возможности расширения и дорабатывать функциональность.​