Новая папка(2)/Новый текстовый документ.txtНовый текстовый документ(2).txt
- Где же я это записал…
Тяжелые предпосылки
Вопрос оптимизации написания документов родился в суете выполнения задач. Частые переключения между пайплайнами, мониторингом, автоматизацией, RnD, поддержкой и детальным списанием времени не давали сосредоточиться на документировании.
Логировать историю
Мне требовалось логировать свои действия, дополнять тексты картинками, ссылками и метками времени, не допуская пересечений тем в одном и том же черновике. Делать нужно было так, чтобы потом можно было легко вспомнить ход работ.
Несколько раз логирование Putty/Bash помогало восстановить запутанную последовательность работы на проде. Не игнорируйте такую возможность.
Публикация
В дальнейшем я хотел превратить черновик в рабочий документ и опубликовать его в рамках проектной документации. В итоге получилось красиво выйти за границы.
Целью было создавать черновики с расширенным форматированием и работать с документацией как с кодом.
Это позволило экономить время на форматировании и переводе в стандартный публикуемый формат.
Онлайн-формат
В итоге формат Markdown+Git позволил автоматически генерировать онлайн-документацию. Бонусом стал офлайн-режим, доступный из кеша браузера. В закрытых сетях заказчика, в самолете и там, где нет интернета, этот режим очень пригодился. Заказчики тоже его оценили.
Формат Markdown используется в Gitlab, YouTrack, некоторых мессенджерах и распознается всеми моделями LLM.
Shared drafts
Если ваша работа не связана с финансами, то ваши черновики не должны быть скрыты. Наоборот, позволяйте работать с ними совместно.
Мое стремление сделать черновики общедоступными дало толчок к созданию “документации как кода”. Команда девопс освободилась от безымянных текстовых файлов и проблемы поиска, “где это было записано?”. Тут нет проблем с разными версиями Word, поехавшими картинками и тому подобным. Плюсом из черновика сразу получается онлайн-версия и красивый и строгий PDF.
Документация сегодня
- пишется в формате Markdown (редактор Typora или аналогичный с автосохранением + коммиты в IDEA/PyCharm)
- хранится в Gitlab (доступна всем сотрудникам по ролевой модели, поддерживает многопользовательское редактирование)
- автоматически собирается в онлайн-версию в контейнере Docsify (обновление кода каждую минуту); сайты пробрасываются в интернет с помощью DNS
- легко экспортируется в PDF с одинаковым оформлением Vue.js как для сайта, так и для файла
- диаграммы создаются в формате Drawio (outline) и Mermaid (inline)
- диаграммы экспортируются в svg (и изредка в png для несовместимых платформ) и включают в себя интегрированный исходник
Чего не хватает?
Большинству пользователей не интересно единое место, где хранится документация и что ее можно там редактировать в многопользовательском режиме. Редакторов-контрибьюторов единицы, а простых пользователей много. Для них важно быстро найти нужный документ в актуальной версии, легко им поделиться. Отсюда есть пара вопросов, каким образом:
- Составлять автоматический список документации.
- Ранжировать ссылки в тексте по актуальности документов (не в плане наличия свежих правок, а правок по сути - ведь никому не нужен документ, оказавшийся вверху списка только благодаря косметическим правкам).
- Допустить режим мелких правок прямо в документе, без необходимости работы с исходником.
- Актуализировать документацию “пачкой”, когда некоторые части документации взаимосвязаны и частично либо полностью переиспользуются.
- Генерировать документацию автоматически, поскольку она очень быстро устаревает.
- Приводить к соответствию не только саму документацию, но и напоминать о необходимости скорректировать либо дополнить связанную реплику сотрудника в публичном канале или коммьюнити. По таким репликам в первую очередь складывается мнение об авторитетности (слова человека, имеющего отношение к документации, первостепенны нежели сама документация, это сложившийся факт).
Третий пункт уже встречается в некоторых платформах, например Discourse. А прийти к структурированной документации поможет ИИ.