Войти через соцсеть:
Войти через email:
Сложность понимания требований и стандартов: Иногда требования и стандарты, предъявляемые к гост документации, могут быть сложными для понимания и интерпретации.
Необходимость знания специфики отрасли: Для написания гост документации требуется глубокое понимание специфики отрасли или области, к которой относится продукт или услуга.
Многочисленные правила и нормы: В гост документации часто приходится учитывать многочисленные правила, нормы и стандарты, что может затруднять процесс написания.
Необходимость соблюдения точности и четкости: В гост документации важно соблюдать точность и четкость формулировок, чтобы избежать недопониманий и ошибок.
Требования к оформлению и форматированию: Гост документация обычно имеет строгое оформление и форматирование, что может создавать трудности при создании документа.
Необходимость постоянного обновления: Гост документация должна постоянно обновляться и корректироваться в соответствии с изменениями требований и стандартов, что также может быть сложным и трудоемким процессом.
Сложность согласования с заказчиком или контрагентами: При написании гост документации может возникнуть необходимость согласования ее содержания с заказчиком или контрагентами, что иногда может привести к затянутому процессу утверждения документа.
Часто над документацией работают не только технические писатели, но и инженеры из разных команд, поэтому на начальном этапе многие термины, относящиеся, например, к Kubernetes, пишутся по-разному: кто-то использует сленг, кто-то — латиницу, а кто-то — кириллицу. Конечно, затем черновик документации попадает к техническому писателю и корректору, которые приведут его в надлежащий вид, но всё это занимает дополнительное время. Да и человек, пусть даже и специально обученный, может допустить ошибку или просто что-то пропустить.
Чтобы навести порядок в терминологии, а заодно и исправлять опечатки «на подлёте», мы решили создать специальный спелл-чекер и с его помощью автоматизировать проверку орфографии.
1. Проблема: слабо задокументированные продукты и техписатели «на обочине» бизнеса
Продукт A:
- много документации;
- неструктурированная;
- частично неактуальная.
Продукт B:
- часть документации из продукта А;
- нет пользовательской документации;
- внутренняя документация не структурирована.
Продукт C:
- есть пользовательская документация;
- пробелы во внутренней документации;
- документация плохо структурирована.
Техписатели работают по модели «документация как сервис» и ждут заявок от продуктовых команд. Команды тем временем продолжают работать в огне и писать документацию как умеют, не прибегая к помощи техписателей.
Задача: включить техписателей в процесс разработки и повысить качество документации.
2. Решение:
2.1. Разработка структуры внутренней и внешней документации (покажу на примере шаблонов);
2.2 Структуризация существующей документации и выявление пробелов;
2.3. Распределение зон ответственности (включение техписателей в проектные команды, развитие техписательских компетенций в условиях специализации);
2.4. Синхронизация документирования с продуктовыми релизами;
2.5. Запуск внутренних техписательских митапов для обмена знаниями.
3. Проблемы и точки роста:
3.1. Отставание документации (отстает на один цикл релиза или пишется в огне);
3.2. Оценка трудозатрат.
Когда в организации много документации по ГОСТ, но нет документации для клиентов, возникает вопрос.
Как на основе ГОСТ сделать документацию для клиентов, чтобы с ней было интересно, удобно и приятно работать?
При этом требуется организовать систему управления документацией так, чтобы затраты не выросли. Ошибок и расхождений тоже не должно быть.
В своем докладе поделюсь, как мы как решили эту задачу.
Спойлер: сделали единый источник данных о характеристиках изделий, подготовили сайт с контентом для клиентов, выстроили процесс изменения документов, настроили шаблоны по ГОСТ.
Поделюсь практическим опытом, расскажу, какие инструменты использовали, как внедряли изменения, как оценивали результаты.