Very Special 😉

Ребята и девчата, привет! Хочется с вами посоветоваться. У нас разработчики ведут новый проект, и встроенную документацию (ака описание встроенного языка) решили "писать сами". Сейчас они хранят это дело, как мне показали, в Confluence, в виде каталогов и файлов формата md. А меня на днях "попросили вычитать". Но меня волнует такой аспект: предполагается работа с этими markdown-файлами "просто через git", и есть подозрение, что если оставить все в текущей организации, с развитием этого встроенного языка, я рискую потерять "контроль" над тем, что происходит. Хотелось бы спросить у тех, кто работает с mardown, как вы организуете хранение файлов, как можно, например, "хотя бы оценить объем текста", как отслеживаете изменения этого текста (например, если документы и их изменения для следующих версий планируется отдавать на перевод)? Пока мне не кажется управляемой куча папок и файлов, которую мне хотят "просто выгрузить из confluence". И это немного напрягает...

У нас есть MD файлы на гитхабе в проекте и негласный договор, что на все ПРы по документации ставят меня в ревьюеры) а так на гите можно через diff это как-то отслеживать. Гит - удобная в этом плане штука, просто не user-friendly. А для переводов вообще есть gitlocalize - прямо отдельный открытый инструмент) не очень крутой, но очень понятный, работает с гитхабом.
Правда, я не очень поняла, как в вашей схеме оказался конфлюенс 🤔

Разработчики начачали в конфлюенсе "писать" эту доку. У нас этот проект только начинается, и они выбрали его из удобства для себя. Я ещё не знаю, планируют ли они из git загружать мою правку в свой конфлюенс обратно. Ещё нет четкого порядка. (поэтому у меня и вопросы). У меня потенциальная задача не только в том, чтобы разово отправить на перевод доку для какой-то версии. Задача в том, чтобы для последующих выпусков этой версии, отслеживать изменения и не пропустить эту самую отправку на перевод. В предыдущем проекте у нас для этого была своя база данных, в которой мы отслеживали состояния каждого текста - у него стояли признаки типа "требуется редактура", "требуется перевод", "требуется перенос в ветку следующей версии продукта"

Может, так же договориться, чтобы при изменениях в конфлюенс тогда отмечали вас? Сделать типа шаблона страницы в конфлюенс с необходимостью тегать ревьюера

"удобная в этом плане штука, просто не user-friendly"

Ржака

ну дык реально гит это удобно, но порог вхождения есть все-таки. Я где-т ополтора года работаю с ним и вот если не делать это прямо каждый божий день, все забывается и сидишь потом тупишь :)

Я пока не могу согласиться. Гит - еще один способ хранить документации. У нас до перехода на markdown был свой способ (вроде базы данных), в котором были свои налаженные инструменты (отчеты, в которых можно было моментально получить спиоск измененных объектов, список объектов, требующих на данный момент перевода, как-то мигрировать описания "мержить" их между версиями, особенно если один объект меняют по-разному в двух парарелльных версиях). Из коробки в гите же всего этого счастья нет.

У нас были инструменты многочисленных проверок (ссылок на объекты), контроля самих описаний (что мол этот объект в этой версии это точно "такой" объект в следующей версии). можно было даже выгурзить в ворд для анализа переводчикам объема и планированировани их работы.

Использовать гит как базу знаний, это как микроскоп и молоток, только наоборот. Удивлен вашему терпению и приспособленности

это даже не база знаний, планируется именно храние "описания встроенного языка"?, вроде того, как у Microsoft справочник по языку  С++. только мы обычно его пользователям показываем не снаружи, а в своей справочной системе

коллеги, есть у кого-то опыт ведения технического блога? выбор платформы, процессы. или статьи, которые можно почитать

Ты хочешь именно на своём сайте? Если так, у вас же Hugo уже есть, он прекрасен.

отдельно от доки хотим

и что-нибудь более-менее из коробки

конфлюэнс здесь явно лишний, в нашем параллельном проекте начинали вести доку в конфе, потом стали дублировать в md и через гитбук верстать статический сайт, сейчас постепенно отказываются от конфы, ведут репы в гите с маркдауном, развернули движок на VuePress
весь процесс ревью и обсуждения в гитхабе

у hugo норм темки для блогов, если ничего сложного по разметке не требуется, а только дата пост - дата пост, хоть на гитлаб pages разверни

А если требуется сложное, то задача фронтендеру да и всё.

Ну сделайте отдельным проектом. Тем на выбор тыща штук, в том числе заточенных под блоги. Просто раз вы с этим инструментом научились работать, зачем зоопарк расширять?