Техническая документация

Сложность понимания требований и стандартов: Иногда требования и стандарты, предъявляемые к гост документации, могут быть сложными для понимания и интерпретации.

Необходимость знания специфики отрасли: Для написания гост документации требуется глубокое понимание специфики отрасли или области, к которой относится продукт или услуга.

Многочисленные правила и нормы: В гост документации часто приходится учитывать многочисленные правила, нормы и стандарты, что может затруднять процесс написания.

Необходимость соблюдения точности и четкости: В гост документации важно соблюдать точность и четкость формулировок, чтобы избежать недопониманий и ошибок.

Требования к оформлению и форматированию: Гост документация обычно имеет строгое оформление и форматирование, что может создавать трудности при создании документа.

Необходимость постоянного обновления: Гост документация должна постоянно обновляться и корректироваться в соответствии с изменениями требований и стандартов, что также может быть сложным и трудоемким процессом.

Сложность согласования с заказчиком или контрагентами: При написании гост документации может возникнуть необходимость согласования ее содержания с заказчиком или контрагентами, что иногда может привести к затянутому процессу утверждения документа.

Часто над документацией работают не только технические писатели, но и инженеры из разных команд, поэтому на начальном этапе многие термины, относящиеся, например, к Kubernetes, пишутся по-разному: кто-то использует сленг, кто-то — латиницу, а кто-то — кириллицу. Конечно, затем черновик документации попадает к техническому писателю и корректору, которые приведут его в надлежащий вид, но всё это занимает дополнительное время. Да и человек, пусть даже и специально обученный, может допустить ошибку или просто что-то пропустить.

Чтобы навести порядок в терминологии, а заодно и исправлять опечатки «на подлёте», мы решили создать специальный спелл-чекер и с его помощью автоматизировать проверку орфографии.

1. Проблема: слабо задокументированные продукты и техписатели «на обочине» бизнеса

Продукт A:

- много документации;

- неструктурированная;

- частично неактуальная.

Продукт B:

- часть документации из продукта А;

- нет пользовательской документации;

- внутренняя документация не структурирована.

Продукт C:

- есть пользовательская документация;

- пробелы во внутренней документации;

- документация плохо структурирована.

Техписатели работают по модели «документация как сервис» и ждут заявок от продуктовых команд. Команды тем временем продолжают работать в огне и писать документацию как умеют, не прибегая к помощи техписателей.

Задача: включить техписателей в процесс разработки и повысить качество документации.

2. Решение:

2.1. Разработка структуры внутренней и внешней документации (покажу на примере шаблонов);

2.2 Структуризация существующей документации и выявление пробелов;

2.3. Распределение зон ответственности (включение техписателей в проектные команды, развитие техписательских компетенций в условиях специализации);

2.4. Синхронизация документирования с продуктовыми релизами;

2.5. Запуск внутренних техписательских митапов для обмена знаниями.

3. Проблемы и точки роста:

3.1. Отставание документации (отстает на один цикл релиза или пишется в огне);

3.2. Оценка трудозатрат.

Когда в организации много документации по ГОСТ, но нет документации для клиентов, возникает вопрос.

Как на основе ГОСТ сделать документацию для клиентов, чтобы с ней было интересно, удобно и приятно работать?

При этом требуется организовать систему управления документацией так, чтобы затраты не выросли. Ошибок и расхождений тоже не должно быть.

В своем докладе поделюсь, как мы как решили эту задачу.

Спойлер: сделали единый источник данных о характеристиках изделий, подготовили сайт с контентом для клиентов, выстроили процесс изменения документов, настроили шаблоны по ГОСТ.

Поделюсь практическим опытом, расскажу, какие инструменты использовали, как внедряли изменения, как оценивали результаты.