Документация Компании АГБИС

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

Документация - крайне необходимая вещь в условиях наличия большого количества процессов, схем действий, и вообще вала информации обо всем. В общем это как раз то, что нам очень нужно :-).
Проще один раз записать, чем рассказывать устно многократно.
Каждый сотрудник должен подумать, если он отвечает на какой-то вопрос, будет ли этот ответ полезен в дальнейшем. Если будет полезен - лучше записать этот вопрос и этот ответ. Если действовать по такому принципу, то со временем накопится именно то, что называется Базой знаний.

Основные понятия

Проект - это обособленный набор услуг, программных модулей или товаров, которые компания предоставляет своим клиентам.
База данных - это средство описания некоторых бизнес процессов.
Документацией базы данных называется совокупность документов, описывающих настройку и выполнение бизнес процессов.
Сотрудник компании - работник компании, в том числе сотрудник технической поддержки или программист.
Партнер компании - сторонняя организация, имеющая партнерские договоренности с нашей компанией на выполнение каких-то услуг нашим клиентам или поставку им товаров.
Администратор - работник организации клиента или сторонний специалист (в том числе сотрудник компании-партнера), выполняющий функции настройки и администрирования проектов.

Документация проекта

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

Разделы и подразделы документации проекта, базовая структура:
Общая информация
Текст, посвященный общей информации о проекте, должен находиться непосредственно на странице проекта.
Подразделы:
Цель проекта - кратко описываем зачем проект вообще нужен и какие задачи клиента решает. Здесь же можно описать преимущества и почему клиент должен выбрать именно наше решение.
Текущий статус - проект запущен или нет.
Роли в проекте - сотрудники компании и какие задачи по проекту они выполняют.
Миссия проекта - более полное описание принципов проекта и его решений.
Цены - базовые принципы ценообразования, цены или ссылки на коммерческие предложения.

Запуск и сопровождение
Разделы документации, посвященные запуску проектов в работу и их последующему сопровождению. Основным принципом проектов должна быть их простота настройки, чтобы клиентам не требовалось обращаться в техническую поддержку компании. Желательно все моменты запуска описывать в общем доступе в разделе для администраторов. Все руководств должны находиться на отдельных страницах. Это нужно для того, чтобы можно было отправить ссылку непосредственно на страницу по некоторой теме.
Руководство администратора - документация, которая помогает администратору / сотруднику компании выполнить настройку системы.
Руководство технической поддержки - документация, которая доступна сотрудникам технической поддержки компании АГБИС, но недоступна администраторам клиентов.

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

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

Страницы всех документов проекта, ведущие на отдельные страницы, должны вверху страницы содержать ссылку на общую страницу по проекту.

В названии страниц не должно быть цифр в начале названия. 
В названии страниц обязательно должно фигурировать имя проекта, например [[:Руководство администратора Агбис Клиент|Руководство администратора]].

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

Источники документов

Текст документа справки может хранится:

Инструменты формирования документации и механизмы доступа к документации

Документация может быть связана:

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

Стандартный механизм подключения контекстно зависимой справки назначенной на кнопку **Помощь** или к пункту **Документация**

Использование Wiki