мета-данные страницы
Различия
Здесь показаны различия между двумя версиями данной страницы.
Предыдущая версия справа и слева Предыдущая версия Следующая версия | Предыдущая версия Следующая версия Следующая версия справа и слева | ||
документация_агбис [13.01.2020 06:53] Анисютин ↷ Операцией перемещения обновлены ссылки |
документация_агбис [02.09.2021 20:21] admin |
||
---|---|---|---|
Строка 1: | Строка 1: | ||
- | ====== Документирование модулей ====== | + | ====== Документация Компании АГБИС ====== |
+ | ===== Принципы документирования ===== | ||
+ | Документация - крайне необходимая вещь в условиях наличия большого количества процессов, схем действий, и вообще вала информации обо всем. В общем это как раз то, что нам очень нужно :-).\\ | ||
+ | Проще один раз записать, чем рассказывать устно многократно.\\ | ||
+ | Каждый сотрудник должен подумать, если он отвечает на какой-то вопрос, будет ли этот ответ полезен в дальнейшем. Если будет полезен - лучше записать этот вопрос и этот ответ. | ||
+ | Если действовать по такому принципу, то со временем накопится именно то, что называется Базой знаний.\\ | ||
+ | |||
+ | ===== Основные понятия ===== | ||
+ | |||
+ | **Проект** - это обособленный набор услуг, программных модулей или товаров, которые компания предоставляет своим клиентам.\\ | ||
**База данных** - это средство описания некоторых бизнес процессов.\\ | **База данных** - это средство описания некоторых бизнес процессов.\\ | ||
- | **Проект** - это отдельный программный модуль для выполнения группы бизнес процессов.\\ | ||
**Документацией базы данных** называется совокупность документов, описывающих настройку и выполнение бизнес процессов.\\ | **Документацией базы данных** называется совокупность документов, описывающих настройку и выполнение бизнес процессов.\\ | ||
+ | **Сотрудник компании** - работник компании, в том числе сотрудник технической поддержки или программист.\\ | ||
+ | **Партнер компании** - сторонняя организация, имеющая партнерские договоренности с нашей компанией на выполнение каких-то услуг нашим клиентам или поставку им товаров.\\ | ||
+ | **Администратор** - работник организации клиента или сторонний специалист (в том числе сотрудник компании-партнера), выполняющий функции настройки и администрирования проектов.\\ | ||
- | ===== Документация бизнес процесса ===== | ||
- | **[[руководство_пользователя|Руководство пользователя]]** - документация, которая помогает пользователю выполнить свои задачи в раках настроенной системы.\\ | + | ===== Требования по содержанию для клиентов ===== |
- | **[[:Руководство администратора]]** - документация, которая помогает администратору системы:\\ | + | 1. Текст не должен быть перегружен техническими терминами |
- | * настроить модули для работы пользователей, \\ | + | 2. Не забывать про визуализацию (схемы, скриншоты) |
- | * проверить целостность,\\ | + | 3. Текст должен быть разбит на абзацы. Крупные блоки должны иметь заголовок. |
- | * выполнить восстановление системы. \\ | + | 4. Крупные не связанные друг с другом блоки должны быть разными файлами. Например, не должно быть на одной странице настройка функции и ее использование в работе. При этом хорошо иметь файл с содержанием, то есть ссылками на все отдельные файлы относящиеся к теме. |
- | **[[:Руководство ТП]]** - документация, которая доступна сотрудникам технической поддержки компании АГБИС.\\ | + | 5. Не дублировать материал, если что-то уже описано, то давать ссылку. |
- | **[[:Руководство разработчика]]** - документация, которая помогает разработчику дорабатывать систему.\\ | + | |
- | Роли расположены в порядке возрастания уровня доступа. \\ | + | |
- | При регистрации клиента сайте "Документация АГБИС" ему назначается уровень доступа. \\ | + | |
- | При подключении к сайту клиенту доступны все документы его уровня и всех уровней, которые меньше его.\\ | + | |
- | + | ||
- | Документация может быть связана:\\ | + | |
- | * с отдельной формой - в этом случае ее удобно использовать в виде контекстно зависимой справки назначенной на кнопку **Помощь**,\\ | + | |
- | * с отдельным программным модулем - в этом случае ее удобно подключать через пункт **Документация** в главном меню программы,\\ | + | |
- | * с процессом, который затрагивает несколько модулей - в этом случае документация может хранится отдельно от программных модулей на корпоративном сайте или привязываться к ключевым программным модулям.\\ | + | |
+ | ===== Требования к стилистике ===== | ||
+ | 1. Текст должен быть написан от 3 лица. Например "Необходимо открыть локальные настройки Агбис Химчистки и ...". То есть ПЛОХО написать "Открываем настройки" и уж тем более "Открываешь настройки". | ||
+ | 2. В одном предложении одинаковые слова нужно заменять синонимами. Например, "Нужно, необходимо, требуется". | ||
===== Документация проекта ===== | ===== Документация проекта ===== | ||
+ | С помощью документации по проекту клиенты должны понять цель проекта, решаемые им задачи и способ как технически и организационно эти задачи выполняются. В документацию по проекту должны входить разделы по настройке технических средств (для сотрудников компании или для администраторов / ответственных лиц клиентов). Также в документацию могут входить разделы, посвященные внутренним аспектам реализации технических средств, описание внутренней реализации программных модулей, базы данных и т.д.\\ | ||
+ | Основная страница проекта должна быть в открытом доступе, но может содержать внутри себя тэги, ограничивающий просмотр той или иной информации.\\ | ||
- | **Руководство администратора** - инструкции по настройке модуля\\ | + | Разделы и подразделы документации проекта, базовая структура:\\ |
- | **Руководство разработчика** - список задействованных программных модулей и описание механизмов доступа к данным.\\ | + | **Общая информация**\\ |
+ | Текст, посвященный общей информации о проекте, должен находиться непосредственно на странице проекта.\\ | ||
+ | Подразделы:\\ | ||
+ | __Цель проекта__ - кратко описываем зачем проект вообще нужен и какие задачи клиента решает. Здесь же можно описать преимущества и почему клиент должен выбрать именно наше решение.\\ | ||
+ | __Текущий статус__ - проект запущен или нет.\\ | ||
+ | __Роли в проекте__ - сотрудники компании и какие задачи по проекту они выполняют.\\ | ||
+ | __Миссия проекта__ - более полное описание принципов проекта и его решений.\\ | ||
+ | __Цены__ - базовые принципы ценообразования, цены или ссылки на коммерческие предложения.\\ | ||
+ | **Запуск и сопровождение**\\ | ||
+ | Разделы документации, посвященные запуску проектов в работу и их последующему сопровождению. Основным принципом проектов должна быть их простота настройки, чтобы клиентам не требовалось обращаться в техническую поддержку компании. Желательно все моменты запуска описывать в общем доступе в разделе для администраторов. Все руководств должны находиться на отдельных страницах. Это нужно для того, чтобы можно было отправить ссылку непосредственно на страницу по некоторой теме.\\ | ||
+ | [[:руководство_администратора|Руководство администратора]] - документация, которая помогает администратору / сотруднику компании выполнить настройку системы.\\ | ||
+ | [[:руководство_тп|Руководство технической поддержки]] - документация, которая доступна сотрудникам технической поддержки компании АГБИС, но недоступна администраторам клиентов.\\ | ||
- | ===== Инструменты формирования документации и механизмы доступа к документации ===== | + | **Пользовательская документация**\\ |
+ | **[[:руководство_пользователя|Руководство пользователя]]** - документация, которая помогает пользователю выполнить бизнес процесс в рамках настроенной системы.\\ | ||
+ | **Документация для программистов**\\ | ||
+ | **[[:руководство_разработчика|Руководство разработчика]]** - документация, которая помогает разработчику разрабатывать и дорабатывать систему.\\ | ||
- | [[:Документация в программе|Стандартный механизм подключения контекстно зависимой справки назначенной на кнопку **Помощь** или к пункту **Документация**]]\\ | + | <alert warning> |
+ | Страницы всех документов проекта, ведущие на отдельные страницы, должны вверху страницы содержать ссылку на общую страницу по проекту.\\ | ||
+ | </alert> | ||
+ | <code> | ||
+ | В названии страниц не должно быть цифр в начале названия. | ||
+ | В названии страниц обязательно должно фигурировать имя проекта, например [[:Руководство администратора Агбис Клиент|Руководство администратора]]. | ||
+ | </code> | ||
- | <ifauth @programmers> | ||
- | Формирование описания модулей на основе элементов текста модулей программных модулей.\\ | ||
- | [[develop:Автодокументирование программ]]\\ | ||
- | ===== Ограничения области видимости документов ===== | + | При создании новых проектов можно брать базовый шаблон из [[internal:Базовый шаблон страницы проекта]].\\ |
- | Ограничения области видимости документов осуществляется двумя путями:\\ | + | ===== Источники документов ===== |
- | 1) размещением документов в защищенном подкаталоге: | + | |
- | * корневом, который доступен всем, например %%[[:Имя документа]]%%\\ | + | |
- | * internal, который доступен всем сотрудникам АГБИС, например %%[[internal:Имя документа]]%%\\ | + | |
- | * develop, который доступен всем разработчикам АГБИС, например %%[[develop:Имя документа]]%%\\ | + | |
- | 2) скрытием текста для в соответствии с ролью с помощью конструкции\\ | + | |
- | <WRAP box 100%> | + | |
- | %%<%%ifauth @role>\\ | + | |
- | текст\\ | + | |
- | %%<%%/ifauth> | + | |
- | </WRAP> | + | |
- | Текст будет доступен для ролей уровня указанной роли и ролей более высокого уровня. \\ | + | |
- | ==== Для рядового пользователя ==== | + | Текст документа справки может хранится: |
+ | * на сайте https://www.agbis.ru/laundry/school/ | ||
+ | * на сайте https://doc.agb.is/ | ||
+ | * в тексте программного модуля,\\ | ||
+ | * в текстовом файле - в случае различия документа для разных клиентов. | ||
+ | * [[:ссылки_на_курсы_документации_в_б24|Ссылки на курсы документации в Б24]]\\ | ||
- | Для **рядового пользователя** будет виден только текст, на который не наложено никаких ограничений. \\ | ||
- | ==== Для администраторов ==== | ||
- | <WRAP box 100%> | + | ===== Инструменты формирования документации и механизмы доступа к документации ===== |
- | %%<%%ifauth @admin> \\ | + | |
- | %% %%текст будет виден администраторам, сотрудникам техподдержки и программистам и недоступен рядовым пользователям \\ | + | |
- | %%<%%/ifauth> | + | |
- | </WRAP> | + | |
- | ==== Для технической поддержки ==== | + | Документация может быть связана:\\ |
+ | * с отдельной формой - в этом случае ее удобно использовать в виде контекстно зависимой справки назначенной на кнопку **Помощь**,\\ | ||
+ | * с отдельным программным модулем - в этом случае ее удобно подключать через пункт **Документация** в главном меню программы,\\ | ||
+ | * с процессом, который затрагивает несколько модулей - в этом случае документация может хранится отдельно от программных модулей на корпоративном сайте или привязываться к ключевым программным модулям.\\ | ||
- | <WRAP box 100%> | + | [[:документация_в_программе|Стандартный механизм подключения контекстно зависимой справки назначенной на кнопку **Помощь** или к пункту **Документация**]]\\ |
- | %%<%%ifauth @user> \\ | + | |
- | %% %%текст будет виден сотрудникам техподдержки и программистам и недоступен администраторам и рядовым пользователям\\ | + | |
- | %%<%%/ifauth>\\ | + | |
- | </WRAP> | + | |
- | + | ||
- | ==== Для программистов ==== | + | |
- | + | ||
- | <WRAP box 100%> | + | |
- | %%<%%ifauth @programmers> \\ | + | |
- | %% %%текст будет виден только программистам\\ | + | |
- | %%<%%/ifauth>\\ | + | |
- | </WRAP> | + | |
+ | <ifauth @programmers> | ||
+ | Для разработчиков доступно формирование описания модулей на основе элементов текста модулей программных модулей.\\ | ||
+ | [[develop:автодокументирование_программ|Автодокументирование программ]]\\ | ||
</ifauth> | </ifauth> | ||
+ | |||
+ | ===== Использование Wiki ===== | ||
+ | |||
+ | [[:синтаксис_wiki|Синтаксис Wiki]]\\ | ||
+ | [[:drafio_plugin|Пример drawio (диаграммы)]]\\ | ||
+ | [[:как_создавать_страницы_права_доступа|Как создавать страницы, права доступа]]\\ | ||
+ | [[:изменения_в_документации|Изменения в документации]]\\ | ||