Комментарии 27
Поскольку статья в значительной мере про инструменты, попробую снова спросить про то, что вроде бы должно существовать, но не находится.
Ищется инструмент, которому говоришь (в процессе написания) "вот этот кусок текста написан на основании вон тех кусков" (например, требований). И потом оно отслеживает и подсказывает, что если исходные основания изменились - то надо бы все последующее пересмотреть. И далее рекурсивно.
Причем, желательно именно работающий просто с текстами, чтобы не разбивать все вручную на миллион карточек по одному утверждению каждое.
В телеге есть сообщество @docsascode можно ещё там спросить.
Хороший вопрос.
С одной стороны работа с git позволяет отслеживать изменения в документации, связанные с конкретной задачей. Но система трассировки требований тут отсутствует.
Теоретически, можно использовать скрытые теги в комментариях при написании документации и помечать те или иные части документации идентификаторами требований. Тогда поиск по этим идентификаторам будет выдавать те места, где они есть. Но для этого у вас, как минимум, должна быть система ведения бизнес требований, в которой эти требования имеют идентификаторы.
Например, в markdown это будет выглядеть так:
3. Проверить, существует ли такой пользователь. <!--#Требование FR-002 --> Для этого:
* Найти в таблице [users] запись, для которой:В описании при просмотре из git комментария видно не будет, но поиск по 'FR-002' выдаст результат.
Теоретически, можно использовать скрытые теги в комментариях при написании документации
Что напомнило. На самом деле есть еще один инструмент (очень похожий на описанный), который должен бы существовать, но который не очень-то есть. Это overlay редактирование. Когда в отдельном файле пишутся всякие заметки и прочее по документу. И оно способно (понятно, что с ограничениями - чудес не бывает) понимать, что к чему относится, когда нижележащий документ изменился.
Это можно до некоторой степени эмулировать тем же git-om (держим отдельную ветку для исходных документов, отдельную для прокомментированных и изменения из первой сливаем во вторую). Но без поддержки интерфейса с таким работать больно и неудобно.
Но для этого у вас, как минимум, должна быть система ведения бизнес требований, в которой эти требования имеют идентификаторы.
Не пойдет. Именно по причине системы ведения и нумерации требований. Желаемый workflow такой: У меня открыт исходный документ(ы), я его читаю и пишу производный.
И прямо по ходу, написав параграф, я должен иметь возможность (без боли от интерфейса) ткнуть и указать "а это потому что смотри то-то и там-то". Указать не для человека, а для автоматики, которая зависимости отслеживать будет.
В вашей области деятельности, если в процессе такой работы возникают кольцевые зависимости между текстами - вам обычно нужно было-бы их избегать, или это норма и нужно просто их видеть?
В данном случае - это не существенно. Достаточно один шаг зависимости обрабатывать. Чтобы софт говорил "Ой, а тут исходные посылки изменились, надо бы их посмотреть(смотри тут) и вот это, возможно, поправить". После чего оно правится (или нет) и инструменту говорится "теперь тут OK, приведено в соответствие".
Потом шаг повторяется уже с документами более высоких степеней производности.
Если же кольцевая зависимость получится - это авторы документов ранее или поздно сами заметят (хотя можно и сказать) и пускай дальше у них самих голова болит, что с этим делать.
Сама по себе тема кажется интересной. Возникает еще пара вопросов.
Вы хотите иметь возможность ссылаться на совершенно произвольный текст, а не блоки текста какой-либо гранулярности?
Такая линковка кажется очевидно должна быть инвариантной к форматированнию этого текста?
Какие по вашему форматы документов или файлов такой тулинг должен поддерживать - как минимум, как оптимум?
"Не для человека, а для автоматики" - но допустимо ли вообще внедрять какие-либо метаданные для линковки в сам документ/текст, или система должна работать исключительно "снаружи"?
После нажатия "ОК" без изменений в зависимом тексте, "цепочка" запросов на проверку изменений должна закончиться или продолжиться до всех листьев? Со стороны кажется что должна закончиться, т.к. если "дети" зависят от невыраженных в тексте "родителя" предположений о цепочке выводов, то вероятно и сами выводы в детях сформированны или слинкованны неверно.
Допустимо ли чтобы этот тулинг был консольным, или по вашему он должен быть гуевым, или интегрироваться в какие-либо среды и редакторы - какие? Что в вашем представлении "без боли от интерфейса"?
Я бы посмотрел на примерный воркфлоу как вы его представляете в виде скринкаста, моков или схем.
Примеры подобных по смыслу систем я увидел, но они так или иначе предполагают работу в некотрой среде и привязку идентификаторов к блокам текста на которые линковка опирается. По сути каждый заголовок и абзац становится "карточкой", просто внутри тула собирается в один документ, и часто трекинг версий у них тоже свой.
Елси бы хватало линковки на только документы, то можно было бы относительно тривиально построить такую систему на базе хеширования документов, что было бы очень гибко в плане форматов и подходу к хранению зависимостей. Если учитывать хеши ссылок в документе при вычислении самого хеша документа, возникает проблема с кольцевыми ссылками (их нельзя будет нормально решить без выноса кольцевых зависимостей в неразрывный документ). Учитывать их или нет зависит от ответа на вопрос о цепочках - как я себе представляю, возможны разные интерпретации "как правильно". Теряется возможностью линковки к произвольному тексту в документах, это может приводить к проблеме как вы описали мелких "карточек".
Вы хотите иметь возможность ссылаться на совершенно произвольный текст, а не блоки текста какой-либо гранулярности?
Плюс-минус. С точностью до параграфа где-то.
Такая линковка кажется очевидно должна быть инвариантной к форматированнию этого текста?
В пределах разумного.
Какие по вашему форматы документов или файлов такой тулинг должен поддерживать - как минимум, как оптимум?
Идеально - все, из чего текст выдирается. Реалистично - любой текстовый формат.
"Не для человека, а для автоматики" - но допустимо ли вообще внедрять какие-либо метаданные для линковки в сам документ/текст, или система должна работать исключительно "снаружи"?
В редактируемом документе (который ссылается и который пишется) - можно внедрять. Но, если он текстовый - нежелательно, ибо будет глаза мозолить и все замусоривать. Для тех документов, на которые ссылаются - рядом. Потому что они снаружи приходят, где всей этой системой не пользуются, а тупо шлют очередную версию Word-файла или PDF-ки.
После нажатия "ОК" без изменений в зависимом тексте, "цепочка" запросов на проверку изменений должна закончиться или продолжиться до всех листьев?
Автоматическая рекурсия - возможна, но не важна. Потому что сценарий использования "открыл документ, а тебе система говорит, что там и там поправить нужно".
Допустимо ли чтобы этот тулинг был консольным, или по вашему он должен быть гуевым, или интегрироваться в какие-либо среды и редакторы - какие? Что в вашем представлении "без боли от интерфейса"?
GUI-евым, конечно. Смотри сценарий. Открываем редактор и видим, что...
Я бы посмотрел на примерный воркфлоу как вы его представляете в виде скринкаста, моков или схем.
Да так и представляю. Сижу, скажем, очередную инструкцию сочиняю. На соседнем экране - исходные документы (всякие требования, регуляции, пожелания, и так далее и тому подобное). В процесс написания тыкаю мышкой "это потому что вот там так хотят, чтобы..."
На следующий день, месяц, год документ открыл - оно пишет, что хотят уже по другому, и мне, возможно, надо вот тут и тут подправить.
Дальнейшие навороты по поводу, что документ надо открыть - по вкусу.
Если бы хватало линковки на только документы,
Нет, не хватает. Потому что документы, на которые опираются - внешние и толстые. Нужно на конкретные места внутрь. Которые места будут меняться, когда очередную версию этих документов пришлют.
Их, конечно, скорее всего придется где-то рядом положить, чтобы можно было ссылаться, но залазить прямо внутрь - ну так себе идея. Разве что размеченную копию держать но тогда - смотри вопрос слияний новой версии документа с этой самой копией.
но они так или иначе предполагают работу в некотрой среде и привязку идентификаторов к блокам текста на которые линковка опирается.
Да ладно... Вот ссылка на кусок обсуждаемой статьи. Никаких идентификаторов, чтобы ее поставить, мне внедрять не понадобилось.
Плюс-минус. С точностью до параграфа где-то
Параграфы бывают разные. Где-то один абзац, где-то десять.
Разве что размеченную копию держать но тогда - смотри вопрос слияний новой версии документа с этой самой копией
Word/PDF из внешнего источника скорее всего будет просто куском байтов. Есть, конечно, слабая надежда на то, что Word будет стилями размечен правильно и это можно разобрать, но что-то я такое видел примерно никогда. Так что каким-то образом обрабатывать внутренности документа для интеграции в Вашу систему всё равно придётся.
Вообще наиболее очевидным решением для Вашего случая видится побеседовать с разработчиками правовых справочных систем типа Гарант/Консультант. У них есть "посмотреть текст в предыдущей редакции" до уровня абзаца.
Если говорить про git, то github, gitbook поддерживают ссылки на конкретную ревизию файла. Вот тут есть какой-то механизм ссылок на конкретные версии файлов для OrgMode: https://orgmode.org/worg/org-contrib/org-git-link.html можно посмотреть, подходит ли он для локального репозитория.
Далее алгоритм очевиден: в разрабатываемом Вами документе ссылки на исходные документы проставляются строго на конкретную ревизию. Для обнаружения факта изменений - делаем diff с HEAD. А уж в какое IDE плагином это присобачить - вопрос личных предпочтений.
Параграфы бывают разные. Где-то один абзац, где-то десять.
Ну и пускай. Сослался на здоровенный кусок - будешь получать работу каждый раз, когда этот кусок изменился.
Так что каким-то образом обрабатывать внутренности документа для интеграции в Вашу систему всё равно придётся.
Разумеется. Где-то в условном 'рядом' будет результат обработки. Возможно, с якорями для линковки. Но вот тут присылают новый вариант документа и... что делать будем со всем этим так, чтобы заново вручную якоря не проставлять?
У них есть "посмотреть текст в предыдущей редакции" до уровня абзаца
Это - особой проблемой не является. Выдираем просто текст, кладем в Version Control, потом сравниваем, заглядывая в оригинал, если не поняли.
Но требуется не только смотреть и сравнить версии, но и выделить (не каждый раз вручную) те изменения, которые на твой документ влияют.
Если говорить про git, то github, gitbook поддерживают ссылки на конкретную ревизию файла.
...
Далее алгоритм очевиден: в разрабатываемом Вами документе ссылки на исходные документы проставляются строго на конкретную ревизию.
Да не файл надо. В этом и запрос. Пусть там хоть десяток версий поменялось и все где-то в начале документа заново написано. Но если параграф, на который ссылаешься, не менялся - ничего реагировать не должно.
Идея же в том, чтобы когда тебе новая версия приходит, ты не садишься сам изменения искать, выискивая относящиеся к тебе, и потом еще вспоминая, почему они относятся и где именно в твоем документе тебе что-то изменить по этому поводу надо. А в том, чтобы тебе инструмент подсказал.
Сослался на здоровенный кусок - будешь получать работу каждый раз, когда этот кусок изменился.
Хозяин - барин, конечно, но это же просто неудобно. Допустим, у Вас в исходном документе есть параграф в 20 абзацев, в котором Вам интересны только второй и четырнадцатый абзацы. В новой редакции документа в этом параграфе стало 25 абзацев. Как с этим жить?
И это даже не рассматривая чисто технические вопросы типа того, как определить конец параграфа в plain text документе, например.
что делать будем со всем этим так, чтобы заново вручную якоря не проставлять?
При выбранном способе, очевидно, что практически никак. Следовательно, не менее очевидно, что не стоит на нём зацикливаться.
Это - особой проблемой не является.
Конечно же смотреть нужно не на то, как они сделали вывод блока "посмотреть текст в предыдущей редакции", а как они в своей системе определяют, что данный кусок текста изменился.
Выдираем просто текст, кладем в Version Control, потом сравниваем
Если весь текст документа лежит в VCS, то тем более непонятно, почему нельзя сравнивать конкретную версию с HEAD.
Но требуется не только смотреть и сравнить версии, но и выделить (не каждый раз вручную) те изменения, которые на твой документ влияют.
Тут явно какая-то подмена изначальной постановки задачи, либо я как-то не так понимаю, что в этом абзаце написано. Причём, дальше будет возврат к первоначальной формулировке, которая намного реалистичнее.
Это очень общая постановка вопроса, которая, как мне видится, не решаема на данный момент даже с привлечением нейросетей.
Допустим, в исходном документе в отслеживаемом параграфе заменили единственное слово "рекомендуется" на "обязательно". Каким алгоритмом узнать, влияет ли это на Ваш документ?
Да не файл надо.
Если я правильно забыл вебинар про внутренности git, то он file based by design.
Но если параграф, на который ссылаешься, не менялся - ничего реагировать не должно.
Здесь, как мне видится, произошёл возврат к первоначальной постановке вопроса. Т.е. отслеживаем только факт изменения определённого фрагмента текста исходного документа. Влияют ли данные изменения на текст Вашего документа остаётся на Вашей совести.
Да не файл надо. <...> Но если параграф, на который ссылаешься, не менялся - ничего реагировать не должно.
Вы забываете, что diff работает с файлами, но изменения-то отслеживает построчно (по умолчанию).
Давайте возьмём для примера недавний коммит, сделавший немного шума.
Вы пишете свой документ и в тексте Вам нужно сослаться на определённый абзац, допустим SELINUX SECURITY MODULE, в Ваш документ вставляется ссылка на файл конкретной версии: https://github.com/torvalds/linux/blob/4d939780b70592e0f4bc6c397e52e518f8fb7916/MAINTAINERS
Можно прямо на нужную строку https://github.com/torvalds/linux/blob/4d939780b70592e0f4bc6c397e52e518f8fb7916/MAINTAINERS#L20872, если оно лежит в VCS, то всё равно это неизменная ссылка на данный абзац.
Далее проходит некоторое время и публикуется новая версия документа, т.е. HEAD указывает теперь на эту версию: https://github.com/torvalds/linux/blob/6e90b675cf942e50c70e8394dfb5862975c3b3b2/MAINTAINERS
На отображении diff'а конкретно этого коммита у меня github упорно пишет о поломке независимо от браузера, устройства и провайдера, поэтому ссылочка будет на письмо из списка рассылки, уж извините: https://lore.kernel.org/all/2024101835-tiptop-blip-09ed@gregkh/
Как видим, в выводе diff нет никаких упоминаний об изменении интересующего нас абзаца SELINUX SECURITY MODULE, значит он неизменен.
А если бы Вы ссылались, например, на абзац BAIKAL-T1 PVT HARDWARE MONITOR DRIVER, то в выводе diff он присутствует, значит изменения произошли.
Собственно, осталось написать плагин к IDE в которой Вы разрабатываете свой документ, который будет брать ссылку из Вашего документа (которая на конкретную версию), делать diff с версией из HEAD и как-то Вас оповещать.
Это очень общая постановка вопроса, которая, как мне видится, не решаема на данный момент даже с привлечением нейросетей.Допустим, в исходном документе в отслеживаемом параграфе заменили единственное слово "рекомендуется" на "обязательно". Каким алгоритмом узнать, влияет ли это на Ваш документ?
Это какое-то слишком обширное восприятие. Про понимание смысла нигде не говорилось.
Определяет что влияет - я, когда на этот параграф/кусок текста сослался в производном документе. И должен получить какое-то оповещение, когда этот параграф изменился.
Если я правильно забыл вебинар про внутренности git, то он file based by design.
Этого аргумента(и последующих объяснений) я не понял. Git пускай как хочет, так и хранит. Я про инструмент отслеживания зависимостей "этот кусок текста (A) мы изобрели на основании этих кусков текста(B1, B2, B3...), они изменились, сходите и проверьте что A все еще основаниям соответствует". Который в самом начале этой ветки я заявлял "вроде бы должен существовать, но не существует"
И версии меня интересую только как инструмент реализации. Я на версию вообще не очень ссылаюсь в контексте этого инструмента. Я хочу ссылаться на "Параграфы X, Y, Z из 'Требования регулятора', где написано, что..."
Проблема тут не в том, чтобы определить, что кусок текста изменился, проблема тут сослаться на кусок текста так, чтобы когда где-то в документе еще что-то изменили (или даже кусок текста слегка переставили) -- ссылка не сломалась. Причем сделать так, чтобы задалбливающей ручной расстановки якорей "этот кусок текста имеет id..." не приходилось заниматься. Потому что за этими якорями придется кому-то следить, чтобы "Система должна выводить желтые надписи на зеленом фоне" какой-то стабильный id имела. И авторы этих исходных документов, разумеется, этим заниматься не будут.
Хозяин - барин, конечно, но это же просто неудобно. Допустим, у Вас в исходном документе есть параграф в 20 абзацев, в котором Вам интересны только второй и четырнадцатый абзацы. В новой редакции документа в этом параграфе стало 25 абзацев. Как с этим жить?
Если 2 и 14 не изменились - ничего не должно происходить. Потому что я указал, что приблизительно где-то тут, в районе этого параграфа есть интересующий меня такой-то текст (этих двух абзацев).
А что там у них нумерация сменилась или в "где-то тут" абзацев больше стало - это инструмент как раз должен понимать, что то, что меня интересовало, не поменялось.
"С точностью до параграфа" - это имелось в виду, что оно не должно путать одинаковый текст в разных частях документа.
Если 2 и 14 не изменились - ничего не должно происходить
Логичнее использовать ссылки на абзац, потому что "стало 25 абзацев, но 2 и 14 не изменились" всё же означает, что параграф изменился.
имелось в виду, что оно не должно путать одинаковый текст в разных частях документа
В общем и целом - не будет. Но надо понимать, что diff он тоже не всесильный и традиционный для любых программ as is. Т.е. иногда и ложные срабатывания будут.
Этого аргумента(и последующих объяснений) я не понял. Git пускай как хочет, так и хранит.
Просто напоминание, что формат хранения именно git - файловый и Вам так или иначе придётся иметь с файлами дело, если строить систему на его основе.
проблема тут сослаться на кусок текста так, чтобы когда где-то в документе еще что-то изменили (или даже кусок текста слегка переставили) -- ссылка не сломалась.
Я же даже пример привёл.
https://github.com/torvalds/linux/blob/4d939780b70592e0f4bc6c397e52e518f8fb7916/MAINTAINERS#L20872
Как видите, ссылка не сломалась, не смотря на то, что с тех пор уже накидали много новых версий.
Но есть нюанс: ссылка не сломается, но будет указывать на старую версию документа.
Например, у Вас есть какой-то фрагмент текста, на который Вы сослались в своём документе. Потом, в течении, допустим, пяти лет, выходят новые версии документа, но конкретно этот фрагмент, на который Вы ссылаетесь, на протяжении всех этих пяти лет не меняется вообще. У Вас в документе так и будет ссылка на версию пятилетней давности.
Ну либо городить ещё какой-то кусок софта, который будет также брать ссылку из документа, сравнивать с HEAD и как-то ссылку обновлять. Но как тут сделать также просто, как обнаружить изменение фрагмента через diff, я не знаю.
всё же означает, что параграф изменился.
Если меня интересует изменения во всем параграфе - то я буду ссылаться на весь параграф. А если только на 2 и 14 абзацы - то это явно выраженное "остальные изменения тут меня не интересуют".
Просто напоминание, что формат хранения именно git - файловый и Вам так или иначе придётся иметь с файлами дело, если строить систему на его основе.
Ну так и и говорил, что при помощи git желаемое можно лишь до некоторой степени эмулировать. И, разумеется, придется морщиться от связанных с этим неудобств и ограничений. По хорошему - наверняка что-нибудь свое потребуется.
Как видите, ссылка не сломалась, не смотря на то, что с тех пор уже накидали много новых версий.
...
Но есть нюанс: ссылка не сломается, но будет указывать на старую версию документа.
Вот именно. Мне не такого рода ссылки хочется. А хочется "смотри соседний документ", который рядом(как бы оно не понималось) лежит. Без всякой отсылки к длинной истории и на документ, что был дюжину итераций назад.
В некотором смысле - вот буквально, новый вариант из письма вытащил, записал на место старого, что рядышком в файловой системе лежит - и все работает.
А история - глубже чем "что в прошлый раз было" - это отдельный вопрос, связанный с обсуждаемым (и несуществующим) инструментом лишь косвенно.
Если меня интересует изменения во всем параграфе - то я буду ссылаться на весь параграф
Лично мне непонятно, как определить конец параграфа, например, в plain text документе. Мне видятся только диапазонные ссылки, но это нездоровая вещь, пусть люди поумнее подумают.
В некотором смысле - вот буквально, новый вариант из письма вытащил, записал на место старого, что рядышком в файловой системе лежит - и все работает.
Именно так и есть. Новый вариант из письма закинул в git "и всё работает".
Мне не такого рода ссылки хочется.
Давайте прикинем в стиле модно-молодёжного agile.
Сейчас у Вас имеется исключительно хотение. Можно, конечно, тщательно за ним ухаживать, только вот задачи Ваши от этого вряд ли решатся. При этом никаких особенных препятствий к реализации Ваших желаний как-то не видно.
Разбейте на несколько итераций и будет Вам желаемое:
MVP: плагин к IDE, делающий diff коммит-специфичных ссылок с HEAD и подсвечивающий те, по которым текст изменился;
Обновлятор ссылок. Программа, делающая diff коммит-специфичных ссылок с HEAD и заменяющая не изменившиеся на текущий коммит;
Сервисные: вставляешь ссылку на HEAD, из него достаётся id коммита и формируется ссылка на конкретный коммит.
Лично мне непонятно, как определить конец параграфа, например, в plain text документе. Мне видятся только диапазонные ссылки, но это нездоровая вещь, пусть люди поумнее подумают.
Я, видимо, объяснять не умею. Точное определение параграфа тут ну вот совершенно не нужно. И нужно только для указания "где-то вот тут". А сама ссылка не на параграф как таковой, а на отслеживаемый текст (содержание, не точную позицию).
Вот приблизительно как эта ссылка ведет на фрагмент текста. И в сценарии "я буду ссылаться на весь параграф" искать конца параграфа не придется. Потому что я сам выделю весь интересующий меня текст, который весь параграф. Но проблема с ней - что она не различает один и тот же текст в разных местах документа, поэтому нужно еще дополнительное приблизительное указание, где искать.
содержание, не точную позицию
Как я уже упоминал, если у Вас текст лежит в VCS, то в пределах одного коммита позиция и содержание, фактически, равносильны. Причём, проблема дублирующегося содержания решается полуавтоматически (пока diff справляется).
Потому что я сам выделю весь интересующий меня текст, который весь параграф.
Пока слабаки пишут всякие url shortener'ы, суровые айтишники не пользуются ссылками короче, чем в полстраницы текста :)
Соответственно, Вам всю эту ссылку, длиной, возможно, в десяток абзацев, придётся впихнуть в свой документ. Что, прямо скажем, довольно странное желание.
Можно, конечно, изобрести то самое "рядом" в виде хранилища цитат. Из Вашего документа будет ссылка на цитату, из цитаты ссылка на оригинал документа.
Потенциальная неприятность номер 1 - само промежуточное хранилище. Оно может поломаться, рассинхронизироваться с любым из документов (или даже с обоими сразу) и т.д.
Потенциальная неприятность номер 2 - Вам когда-нибудь понадобиться написать что-то типа постатейного комментария. И у Вас оригинальный документ практически полным составом будет скопирован в хранилище цитат.
По-моему даже диапазонные ссылки выглядят привлекательнее.
Пока слабаки пишут всякие url shortener'ы, суровые айтишники не пользуются ссылками короче, чем в полстраницы текста :)
Это просто очень тупые ссылки, которые я для браузера демонстрировал. Можно же свернуть в какой-нибудь хэш и потом сказать "ищи подходящий текст где-то тут". Торомознее, но сами ссылки короче будут. Что не отменяет того, что в процессе цитирования я буду именно выделять все что надо.
Можно, конечно, изобрести то самое "рядом" в виде хранилища цитат. Из Вашего документа будет ссылка на цитату, из цитаты ссылка на оригинал документа.
Ну так, если, как тут постоянно обсуждение уезжает хотя я на нем не настаивал, используется VC, то именно хранение оригинала и происходит. Так что с этой точки зрения оно равнозначно.
Можно же свернуть в какой-нибудь хэш
Можно...
и потом сказать "ищи подходящий текст где-то тут"
... назад в текст развернуть нельзя ;)
как тут постоянно обсуждение уезжает хотя я на нем не настаивал, используется VC
Я ещё предлагал рассмотреть правовые справочные системы.
VCS хороши тем, что Вы можете на их базе реализовать желаемое прямо сейчас, небольшими усилиями. Ещё и на свободном инструментарии.
то именно хранение оригинала и происходит. Так что с этой точки зрения оно равнозначно
Нет, отличие в дублировании исходного документа.
Вариант 1: ссылки на конкретный коммит git'а.
Вам приходит документ, заливаете его в git, проверяете целостность ссылок, редактируете в ссылках номера строк. Итого, у Вас в системе хранится только один экземпляр документа конкретной редакции.
Вариант 2: ссылки на хранилище цитат.
Вам приходит документ, заливаете его в хранилище документов, проверяете целостность ссылок, выдёргиваете из документа новые версии цитат в хранилище цитат, редактируете ссылки на хранилище цитат. Итого, у Вас в системе хранится два экземпляра документа конкретной редакции: один в хранилище документов, второй - в хранилище цитат.
... назад в текст развернуть нельзя ;)
И не надо. Можно в указанном месте "где-то тут". найти текст, который под хэш подходит. Но хэш придется изобретать ну очень хитрый, чтобы уж слишком не тормозило.
Вам приходит документ, заливаете его в хранилище документов, проверяете целостность ссылок, выдёргиваете из документа новые версии цитат в хранилище цитат, редактируете ссылки на хранилище цитат. Итого, у Вас в системе хранится два экземпляра документа конкретной редакции: один в хранилище документов, второй - в хранилище цитат.
Во всем этом интересует две версии внешнего документа
Первая - то, каким он был. Это либо "хранилище цитат", либо предыдущая версия в VC.
Вторая - то, какой он сейчас. Это либо документ рядом, либо текущая версия в VC (та самая, которую залили).
Так что равнозначно. Что так что так есть и хранятся эти две версии.
Можно в указанном месте "где-то тут". найти текст, который под хэш подходит
Это придётся от "где-то тут" перебирать фрагменты текста разной длины, считать от них хэши и сравнивать. Я, конечно, понимаю, что процессор на компьютере простаивает, но не настолько же.
При том, что диапазонная ссылка будет выглядеть как-то так: номер_начальной_строки - номер_конечной_строки. git diff номера строк показывает, т.е. достаточно их из вывода git diff достать и сравнить. Это явно будет намного быстрее, чем даже CRC какой-нибудь считать.
Во всем этом интересует две версии внешнего документа
Оптимистично, лучше хранить все.
Но если уж Вы так настаиваете, то в VCS по окончании цикла правок можно хранить только одну, текущую. Заливаете новую, цикл правок, опять оставляете только одну.
С хранилищем цитат такой фокус не пройдёт.
Интересная статья. Недавно начал активно использовать ИИ-асистенотов и mermaid, понял, что они не плохо подходят для генерации документации к коду, а также для перевода одной текстовой структуры в другую.
Решил ради интереса и тренировки оформить свой github-профиль, использовал mermaid и deep-seek. Скинул 10 скриншотов статистики в deep-seek, с помощью него распознал табличные данные, попросил посчитать и построить график. Аналогично другие структуры в профиле заводил в различные графики mermaid.
Также пару раз генерировал код для простых библиотек, закидывал код в ИИ и просил написать readme-файл, получалось неплохо. Потом минут за 5 вычищал лишнюю воду и вуаля.
Почему программисты не пишущие документацию не начали использовать ИИ и mermaid+markdown для быстрого и легкого написания документации - не понятно) Ревью текста займет явно меньше времени, чем написать все с нуля.
Так сначала код или док должен быть?
Так как я разработчик, то в своих проектах я сперва пишу код, потом документацию. Хотя и на работе также. Есть верхнеуровневая документация, которая описывает поведение приложения, а я как разработчик уже сам декомпозирую постановку и создаю внутренние библиотеки с документацией.
Будь я аналитиком, то скорее всего сперва генерировал бы документацию, а потом уже кто-то генерировал код по нему.
Не очень уверен, что правильно ответил на вопрос)
Странно, почему никто в комментах не написал про obsidian. В нём и md, и wiki, и куча удобных плагинов, возможность шаблонизации файлов, сниппеты, mermaid и куча всего максимально полезного, включая язык запросов для формирования всяких таблиц для отчётности по файлам (последнее, конечно, больше как баловство, но всё же можно придумать какую-нибудь таблицу с версиями и изменениями по документации). И конечно же, можно его синхронизировать с гитом и также создавать ветки. Сам недавно для написания аналитики настраивал хранилище, но пока не успел комплексно потестить.
Почему я использую doc-as-a-code