Подумываю о переработке довольно значительного объёма документов, единиц триста, довольно объёмных и насыщенных, связанных между собой.
Поделитесь опытом, что на эту тему есть почитать и с самого начала предусмотреть внедрение.
Я не знаю, глоссарии, трансклюзия, шаблоны, всё что угодно.
Тема — сопровождение софта, упор на типовые инструкции, наверное.
Уточнение: основная проблема не в стиле и не в стандартах. Основная проблема в том, что документацию должно быть удобно поддерживать сотрудникам из разных команд.
По стандартам гитхаба сложно что-то переработать. Как мне кажется задача стоит прочесть, отжать до основной ценности (инструкций) написать краткий и по делу манул.
Кое-какую идею я нащупал и сейчас с ней играюсь. Идея почёрпнута в общих чертах из чатика и форума, и вот в чём она заключается.
1: В основном люди пишут документацию в виде огромных портянок, которые страшно лишний раз трогать
2: То, что очевидно для одного человека, может оказаться неочевидным для другого.
3: Разные люди отвечают за разные аспекты поддержки приложения
Берём идею атомарных заметок, трансклюзию, шаблоны, немного иерархии и немного тегов.
Иерархия выглядит, допустим, следующим образом:
Служебная директория
Глоссарий
Выкладка
Мониторинг
Документация разработчиков
Документация сопровождения
Внутри служебной директории, создаются короткие статьи. В этих статьях поясняются термины, описываются отдельные простые элементы.
Когда нужно составить документ для разработчиков или администраторов, мы набираем из служебной директории “кубики”. На “кубики” вешаются тэги.
Внутри документов, которые используют люди с помощью плагина “контент по тегу” кубики компонуются в нужном порядке: все определения, описания операций, контакты, что угодно.
“Человеческие” документы состоят из объяснений, как стыкуются между собой части и почему так сделано.
Попытка применить Zettelkastel-подобную схему в программировании называлась Literate Programming - разбиение программы при написании на маленькие фрагменты с указанием ссылок и документированием. Потом две отдельные программы делали из этой заготовки программу и полную документацию (с оглавлениями и глоссарием). К сожалению, это, как раз и привело к появлению
В обычных производственных системах документирования такого не бывает, наоборот, старая портянка копируется почти без изменений. Вплоть до:
1-ое изделие: Надо разобраться: полгода тебе на анализ, три месяца - на отчет.
2-ое изделие: Ну анализ почти такой же, как и в первый раз, новый только отчет, три месяца на все.
3-е изделие: Знаешь, изделие-то еще и не начинали делать, но пока отчет напишешь, месяца за три, может, сделают?
Задача была несколько сложнее, но мне кажется я подход нащупал.
Существщее отжать, на куски разобрать, куски аккуратно сложить, из них собирать документы с инструкциями, регламентами, объяснениями и чёртом в ступе для людей из разных отделов и разной квалификации.
Мне крайне интересно посмотреть что получиться. Хотя бы на кусочек.
В свое время работая в газпромнефти мы придумали КФК, книгу функционального качества.
Тогда разговора о цифре не было, у нас были огромные талмуды с предметным указателем, оглавлением и индексами, ключевыми словами прочими плюшками. Сейчас ессено сделал бы по другому. Хочу посмотреть как может подучиться в новых реалиях.
