Comments 27
Поскольку статья в значительной мере про инструменты, попробую снова спросить про то, что вроде бы должно существовать, но не находится.
Ищется инструмент, которому говоришь (в процессе написания) "вот этот кусок текста написан на основании вон тех кусков" (например, требований). И потом оно отслеживает и подсказывает, что если исходные основания изменились - то надо бы все последующее пересмотреть. И далее рекурсивно.
Причем, желательно именно работающий просто с текстами, чтобы не разбивать все вручную на миллион карточек по одному утверждению каждое.
В телеге есть сообщество @docsascode можно ещё там спросить.
Хороший вопрос.
С одной стороны работа с git позволяет отслеживать изменения в документации, связанные с конкретной задачей. Но система трассировки требований тут отсутствует.
Теоретически, можно использовать скрытые теги в комментариях при написании документации и помечать те или иные части документации идентификаторами требований. Тогда поиск по этим идентификаторам будет выдавать те места, где они есть. Но для этого у вас, как минимум, должна быть система ведения бизнес требований, в которой эти требования имеют идентификаторы.
Например, в markdown это будет выглядеть так:
3. Проверить, существует ли такой пользователь. <!--#Требование FR-002 --> Для этого:
* Найти в таблице [users] запись, для которой:В описании при просмотре из git комментария видно не будет, но поиск по 'FR-002' выдаст результат.
Теоретически, можно использовать скрытые теги в комментариях при написании документации
Что напомнило. На самом деле есть еще один инструмент (очень похожий на описанный), который должен бы существовать, но который не очень-то есть. Это overlay редактирование. Когда в отдельном файле пишутся всякие заметки и прочее по документу. И оно способно (понятно, что с ограничениями - чудес не бывает) понимать, что к чему относится, когда нижележащий документ изменился.
Это можно до некоторой степени эмулировать тем же git-om (держим отдельную ветку для исходных документов, отдельную для прокомментированных и изменения из первой сливаем во вторую). Но без поддержки интерфейса с таким работать больно и неудобно.
Но для этого у вас, как минимум, должна быть система ведения бизнес требований, в которой эти требования имеют идентификаторы.
Не пойдет. Именно по причине системы ведения и нумерации требований. Желаемый workflow такой: У меня открыт исходный документ(ы), я его читаю и пишу производный.
И прямо по ходу, написав параграф, я должен иметь возможность (без боли от интерфейса) ткнуть и указать "а это потому что смотри то-то и там-то". Указать не для человека, а для автоматики, которая зависимости отслеживать будет.
В вашей области деятельности, если в процессе такой работы возникают кольцевые зависимости между текстами - вам обычно нужно было-бы их избегать, или это норма и нужно просто их видеть?
В данном случае - это не существенно. Достаточно один шаг зависимости обрабатывать. Чтобы софт говорил "Ой, а тут исходные посылки изменились, надо бы их посмотреть(смотри тут) и вот это, возможно, поправить". После чего оно правится (или нет) и инструменту говорится "теперь тут OK, приведено в соответствие".
Потом шаг повторяется уже с документами более высоких степеней производности.
Если же кольцевая зависимость получится - это авторы документов ранее или поздно сами заметят (хотя можно и сказать) и пускай дальше у них самих голова болит, что с этим делать.
Сама по себе тема кажется интересной. Возникает еще пара вопросов.
Вы хотите иметь возможность ссылаться на совершенно произвольный текст, а не блоки текста какой-либо гранулярности?
Такая линковка кажется очевидно должна быть инвариантной к форматированнию этого текста?
Какие по вашему форматы документов или файлов такой тулинг должен поддерживать - как минимум, как оптимум?
"Не для человека, а для автоматики" - но допустимо ли вообще внедрять какие-либо метаданные для линковки в сам документ/текст, или система должна работать исключительно "снаружи"?
После нажатия "ОК" без изменений в зависимом тексте, "цепочка" запросов на проверку изменений должна закончиться или продолжиться до всех листьев? Со стороны кажется что должна закончиться, т.к. если "дети" зависят от невыраженных в тексте "родителя" предположений о цепочке выводов, то вероятно и сами выводы в детях сформированны или слинкованны неверно.
Допустимо ли чтобы этот тулинг был консольным, или по вашему он должен быть гуевым, или интегрироваться в какие-либо среды и редакторы - какие? Что в вашем представлении "без боли от интерфейса"?
Я бы посмотрел на примерный воркфлоу как вы его представляете в виде скринкаста, моков или схем.
Примеры подобных по смыслу систем я увидел, но они так или иначе предполагают работу в некотрой среде и привязку идентификаторов к блокам текста на которые линковка опирается. По сути каждый заголовок и абзац становится "карточкой", просто внутри тула собирается в один документ, и часто трекинг версий у них тоже свой.
Елси бы хватало линковки на только документы, то можно было бы относительно тривиально построить такую систему на базе хеширования документов, что было бы очень гибко в плане форматов и подходу к хранению зависимостей. Если учитывать хеши ссылок в документе при вычислении самого хеша документа, возникает проблема с кольцевыми ссылками (их нельзя будет нормально решить без выноса кольцевых зависимостей в неразрывный документ). Учитывать их или нет зависит от ответа на вопрос о цепочках - как я себе представляю, возможны разные интерпретации "как правильно". Теряется возможностью линковки к произвольному тексту в документах, это может приводить к проблеме как вы описали мелких "карточек".
Вы хотите иметь возможность ссылаться на совершенно произвольный текст, а не блоки текста какой-либо гранулярности?
Плюс-минус. С точностью до параграфа где-то.
Такая линковка кажется очевидно должна быть инвариантной к форматированнию этого текста?
В пределах разумного.
Какие по вашему форматы документов или файлов такой тулинг должен поддерживать - как минимум, как оптимум?
Идеально - все, из чего текст выдирается. Реалистично - любой текстовый формат.
"Не для человека, а для автоматики" - но допустимо ли вообще внедрять какие-либо метаданные для линковки в сам документ/текст, или система должна работать исключительно "снаружи"?
В редактируемом документе (который ссылается и который пишется) - можно внедрять. Но, если он текстовый - нежелательно, ибо будет глаза мозолить и все замусоривать. Для тех документов, на которые ссылаются - рядом. Потому что они снаружи приходят, где всей этой системой не пользуются, а тупо шлют очередную версию Word-файла или PDF-ки.
После нажатия "ОК" без изменений в зависимом тексте, "цепочка" запросов на проверку изменений должна закончиться или продолжиться до всех листьев?
Автоматическая рекурсия - возможна, но не важна. Потому что сценарий использования "открыл документ, а тебе система говорит, что там и там поправить нужно".
Допустимо ли чтобы этот тулинг был консольным, или по вашему он должен быть гуевым, или интегрироваться в какие-либо среды и редакторы - какие? Что в вашем представлении "без боли от интерфейса"?
GUI-евым, конечно. Смотри сценарий. Открываем редактор и видим, что...
Я бы посмотрел на примерный воркфлоу как вы его представляете в виде скринкаста, моков или схем.
Да так и представляю. Сижу, скажем, очередную инструкцию сочиняю. На соседнем экране - исходные документы (всякие требования, регуляции, пожелания, и так далее и тому подобное). В процесс написания тыкаю мышкой "это потому что вот там так хотят, чтобы..."
На следующий день, месяц, год документ открыл - оно пишет, что хотят уже по другому, и мне, возможно, надо вот тут и тут подправить.
Дальнейшие навороты по поводу, что документ надо открыть - по вкусу.
Если бы хватало линковки на только документы,
Нет, не хватает. Потому что документы, на которые опираются - внешние и толстые. Нужно на конкретные места внутрь. Которые места будут меняться, когда очередную версию этих документов пришлют.
Их, конечно, скорее всего придется где-то рядом положить, чтобы можно было ссылаться, но залазить прямо внутрь - ну так себе идея. Разве что размеченную копию держать но тогда - смотри вопрос слияний новой версии документа с этой самой копией.
но они так или иначе предполагают работу в некотрой среде и привязку идентификаторов к блокам текста на которые линковка опирается.
Да ладно... Вот ссылка на кусок обсуждаемой статьи. Никаких идентификаторов, чтобы ее поставить, мне внедрять не понадобилось.
Параграфы бывают разные. Где-то один абзац, где-то десять.
Ну и пускай. Сослался на здоровенный кусок - будешь получать работу каждый раз, когда этот кусок изменился.
Так что каким-то образом обрабатывать внутренности документа для интеграции в Вашу систему всё равно придётся.
Разумеется. Где-то в условном 'рядом' будет результат обработки. Возможно, с якорями для линковки. Но вот тут присылают новый вариант документа и... что делать будем со всем этим так, чтобы заново вручную якоря не проставлять?
У них есть "посмотреть текст в предыдущей редакции" до уровня абзаца
Это - особой проблемой не является. Выдираем просто текст, кладем в Version Control, потом сравниваем, заглядывая в оригинал, если не поняли.
Но требуется не только смотреть и сравнить версии, но и выделить (не каждый раз вручную) те изменения, которые на твой документ влияют.
Если говорить про git, то github, gitbook поддерживают ссылки на конкретную ревизию файла.
...
Далее алгоритм очевиден: в разрабатываемом Вами документе ссылки на исходные документы проставляются строго на конкретную ревизию.
Да не файл надо. В этом и запрос. Пусть там хоть десяток версий поменялось и все где-то в начале документа заново написано. Но если параграф, на который ссылаешься, не менялся - ничего реагировать не должно.
Идея же в том, чтобы когда тебе новая версия приходит, ты не садишься сам изменения искать, выискивая относящиеся к тебе, и потом еще вспоминая, почему они относятся и где именно в твоем документе тебе что-то изменить по этому поводу надо. А в том, чтобы тебе инструмент подсказал.
Это очень общая постановка вопроса, которая, как мне видится, не решаема на данный момент даже с привлечением нейросетей.Допустим, в исходном документе в отслеживаемом параграфе заменили единственное слово "рекомендуется" на "обязательно". Каким алгоритмом узнать, влияет ли это на Ваш документ?
Это какое-то слишком обширное восприятие. Про понимание смысла нигде не говорилось.
Определяет что влияет - я, когда на этот параграф/кусок текста сослался в производном документе. И должен получить какое-то оповещение, когда этот параграф изменился.
Если я правильно забыл вебинар про внутренности git, то он file based by design.
Этого аргумента(и последующих объяснений) я не понял. Git пускай как хочет, так и хранит. Я про инструмент отслеживания зависимостей "этот кусок текста (A) мы изобрели на основании этих кусков текста(B1, B2, B3...), они изменились, сходите и проверьте что A все еще основаниям соответствует". Который в самом начале этой ветки я заявлял "вроде бы должен существовать, но не существует"
И версии меня интересую только как инструмент реализации. Я на версию вообще не очень ссылаюсь в контексте этого инструмента. Я хочу ссылаться на "Параграфы X, Y, Z из 'Требования регулятора', где написано, что..."
Проблема тут не в том, чтобы определить, что кусок текста изменился, проблема тут сослаться на кусок текста так, чтобы когда где-то в документе еще что-то изменили (или даже кусок текста слегка переставили) -- ссылка не сломалась. Причем сделать так, чтобы задалбливающей ручной расстановки якорей "этот кусок текста имеет id..." не приходилось заниматься. Потому что за этими якорями придется кому-то следить, чтобы "Система должна выводить желтые надписи на зеленом фоне" какой-то стабильный id имела. И авторы этих исходных документов, разумеется, этим заниматься не будут.
Хозяин - барин, конечно, но это же просто неудобно. Допустим, у Вас в исходном документе есть параграф в 20 абзацев, в котором Вам интересны только второй и четырнадцатый абзацы. В новой редакции документа в этом параграфе стало 25 абзацев. Как с этим жить?
Если 2 и 14 не изменились - ничего не должно происходить. Потому что я указал, что приблизительно где-то тут, в районе этого параграфа есть интересующий меня такой-то текст (этих двух абзацев).
А что там у них нумерация сменилась или в "где-то тут" абзацев больше стало - это инструмент как раз должен понимать, что то, что меня интересовало, не поменялось.
"С точностью до параграфа" - это имелось в виду, что оно не должно путать одинаковый текст в разных частях документа.
всё же означает, что параграф изменился.
Если меня интересует изменения во всем параграфе - то я буду ссылаться на весь параграф. А если только на 2 и 14 абзацы - то это явно выраженное "остальные изменения тут меня не интересуют".
Просто напоминание, что формат хранения именно git - файловый и Вам так или иначе придётся иметь с файлами дело, если строить систему на его основе.
Ну так и и говорил, что при помощи git желаемое можно лишь до некоторой степени эмулировать. И, разумеется, придется морщиться от связанных с этим неудобств и ограничений. По хорошему - наверняка что-нибудь свое потребуется.
Как видите, ссылка не сломалась, не смотря на то, что с тех пор уже накидали много новых версий.
...
Но есть нюанс: ссылка не сломается, но будет указывать на старую версию документа.
Вот именно. Мне не такого рода ссылки хочется. А хочется "смотри соседний документ", который рядом(как бы оно не понималось) лежит. Без всякой отсылки к длинной истории и на документ, что был дюжину итераций назад.
В некотором смысле - вот буквально, новый вариант из письма вытащил, записал на место старого, что рядышком в файловой системе лежит - и все работает.
А история - глубже чем "что в прошлый раз было" - это отдельный вопрос, связанный с обсуждаемым (и несуществующим) инструментом лишь косвенно.
Лично мне непонятно, как определить конец параграфа, например, в plain text документе. Мне видятся только диапазонные ссылки, но это нездоровая вещь, пусть люди поумнее подумают.
Я, видимо, объяснять не умею. Точное определение параграфа тут ну вот совершенно не нужно. И нужно только для указания "где-то вот тут". А сама ссылка не на параграф как таковой, а на отслеживаемый текст (содержание, не точную позицию).
Вот приблизительно как эта ссылка ведет на фрагмент текста. И в сценарии "я буду ссылаться на весь параграф" искать конца параграфа не придется. Потому что я сам выделю весь интересующий меня текст, который весь параграф. Но проблема с ней - что она не различает один и тот же текст в разных местах документа, поэтому нужно еще дополнительное приблизительное указание, где искать.
Пока слабаки пишут всякие url shortener'ы, суровые айтишники не пользуются ссылками короче, чем в полстраницы текста :)
Это просто очень тупые ссылки, которые я для браузера демонстрировал. Можно же свернуть в какой-нибудь хэш и потом сказать "ищи подходящий текст где-то тут". Торомознее, но сами ссылки короче будут. Что не отменяет того, что в процессе цитирования я буду именно выделять все что надо.
Можно, конечно, изобрести то самое "рядом" в виде хранилища цитат. Из Вашего документа будет ссылка на цитату, из цитаты ссылка на оригинал документа.
Ну так, если, как тут постоянно обсуждение уезжает хотя я на нем не настаивал, используется VC, то именно хранение оригинала и происходит. Так что с этой точки зрения оно равнозначно.
... назад в текст развернуть нельзя ;)
И не надо. Можно в указанном месте "где-то тут". найти текст, который под хэш подходит. Но хэш придется изобретать ну очень хитрый, чтобы уж слишком не тормозило.
Вам приходит документ, заливаете его в хранилище документов, проверяете целостность ссылок, выдёргиваете из документа новые версии цитат в хранилище цитат, редактируете ссылки на хранилище цитат. Итого, у Вас в системе хранится два экземпляра документа конкретной редакции: один в хранилище документов, второй - в хранилище цитат.
Во всем этом интересует две версии внешнего документа
Первая - то, каким он был. Это либо "хранилище цитат", либо предыдущая версия в VC.
Вторая - то, какой он сейчас. Это либо документ рядом, либо текущая версия в VC (та самая, которую залили).
Так что равнозначно. Что так что так есть и хранятся эти две версии.
Интересная статья. Недавно начал активно использовать ИИ-асистенотов и mermaid, понял, что они не плохо подходят для генерации документации к коду, а также для перевода одной текстовой структуры в другую.
Решил ради интереса и тренировки оформить свой github-профиль, использовал mermaid и deep-seek. Скинул 10 скриншотов статистики в deep-seek, с помощью него распознал табличные данные, попросил посчитать и построить график. Аналогично другие структуры в профиле заводил в различные графики mermaid.
Также пару раз генерировал код для простых библиотек, закидывал код в ИИ и просил написать readme-файл, получалось неплохо. Потом минут за 5 вычищал лишнюю воду и вуаля.
Почему программисты не пишущие документацию не начали использовать ИИ и mermaid+markdown для быстрого и легкого написания документации - не понятно) Ревью текста займет явно меньше времени, чем написать все с нуля.
Так сначала код или док должен быть?
Так как я разработчик, то в своих проектах я сперва пишу код, потом документацию. Хотя и на работе также. Есть верхнеуровневая документация, которая описывает поведение приложения, а я как разработчик уже сам декомпозирую постановку и создаю внутренние библиотеки с документацией.
Будь я аналитиком, то скорее всего сперва генерировал бы документацию, а потом уже кто-то генерировал код по нему.
Не очень уверен, что правильно ответил на вопрос)
Странно, почему никто в комментах не написал про obsidian. В нём и md, и wiki, и куча удобных плагинов, возможность шаблонизации файлов, сниппеты, mermaid и куча всего максимально полезного, включая язык запросов для формирования всяких таблиц для отчётности по файлам (последнее, конечно, больше как баловство, но всё же можно придумать какую-нибудь таблицу с версиями и изменениями по документации). И конечно же, можно его синхронизировать с гитом и также создавать ветки. Сам недавно для написания аналитики настраивал хранилище, но пока не успел комплексно потестить.
Почему я использую doc-as-a-code