От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Спасибо! Стремимся популяризировать полезные практики 🤝

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Спасибо, стараемся 🫶

Как мы пытались в Docs as code и проиграли

У нас в роадмапе есть несколько фич, которые это решат:

1. Трассировка требований. Можно будет связывать отдельные куски текста в рамках каталога.

2. Отслеживание изменений. В навигации будет показываться, какие статьи изменились или добавились.

Можем подробнее обсудить, если интересно!

Как мы пытались в Docs as code и проиграли

Добавила гитхаб в описание профиля)

Как мы пытались в Docs as code и проиграли

Столкнулись в свое время со всеми проблемами из статьи. Написали свой движок для доки:

• Десктопное и браузерное приложение для редактирования. Не надо настраивать локальный сервер и пользоваться IDE: просто качаешь приложение и начинаешь писать.

• Визуальный редактор с диаграммами. Чтобы не вдаваться в детали языка разметки.

• Упрощенный Git-клиент в интерфейсе. Чтобы не изучать команды, а тыкать кнопки.

• Комментарии для ревью. Это просто удобно.

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

Так что мы у Docs as Code выиграли😅 Уже несколько лет технические и нетехнические специалисты работают вместе.

Создание системы документирования, или как в Cloud.ru от «ворда» к docs as code за месяц переходили. Часть 2

4 недели - это сильно! Про техническую часть понятно, любопытно узнать процессные нюансы:

1. Как долго онбордите новичков без опыта в dac? Быстро втягиваются?

2. Как готовите драфты статей? Если писать сразу в языке разметки, фокус уходит в оформление, а не смысл. Есть ли централизованный подход?

3. Как проводите ревью? Через мерж реквесты?

4. Где и как решаете конфликты? Прямо в гитлабе?

5. Что делают техписы, когда возникают ошибки? У вас в команде остался инженер или ребята сами справляются?

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

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

1. Устанавливаешь в браузер экстеншен с проверками (если работаешь в облачном ворде, конечно).

2. Добавляешь стандартные проверки типа орфографии, пунктуации, типографики, битых ссылок, тавтологий.

3. Создаешь свои проверки: корпоративный стиль, стоп-слова и так далее.

4. Кликаешь "Проверить" и смотришь все ошибки.

Ручную проверку такая штука бы не отменила, но время сэкономила.

Как эффективно добавлять документацию при разработке продукта?

Как показывает практика, лучшие решения появляются на стыке двух и более подходов. Перекладывая на документацию (ИМХО) - круто, когда писателя подключают на двух этапах:

1. Согласование ТЗ от аналитика. Писатель узнает изначальную проблему, предложенное решение, а также ревьюит макет от дизайнера. Можно вовремя заметить кривой воркфлоу и непонятные названия кнопок (в случае, если нет UX-писателя).

2. Внутренняя приемка. Писателю не стоит вовлекаться в весь процесс разработки - слишком времязатратно. Но так как в середине проекта что-то могут поменять, эти изменения здорово заметить на этапе приемки, когда разработчики демонстрируют результат аналитику и PO. Тогда и у разработчиков будет время что-то исправить, и у писателя оценить объем своей задачи.