разработчками.
В наличии кодовая база на языке N. Комментарии к сигнатурам и есть документация. Проблема в том, что для разработчиков такое положение удобно, для писателей — нет. Им не нравится идти в исходный код чтобы править документацию. Сталкиваетесь ли вы с подобным? Если да, то как решали или какие подходы у вас в целом были?
Сталкивались. Генерация документации из кода + техписатели которые способны контрибьютить прямо в код, в системе контроля версий конечно же.
тут условие как я понял что техписам неудобненько) я бы их на мороз отправил, а остальные пусть учатся коммиты делать)
я не понимаю как может быть неудобненько когда генерируется готовый справочник на 500+ страниц
Под неудобно я имел ввиду делать коммиты в исходный код.
поймите меня правильно: неудобно, пока нет профитов. и я не премию имею в виду профит это когда руководитель предложил мне сравнить ситуацию 1: в которой я, техпис, правлю тип данных сам руками, в табличке в конфлюенсе и ситуацию2: в которой я, техпис, ничего не правлю оно само правится
На одном из проектов разработчики писали комментарии, а мы, писатели, их редактировали. Затем из комментов собирали доку. Подучились, пообщались с разработчиками и вперед. Это просто была одна из базовых задач писателей.
Редактировали прямо в коде?
что именно? я попробую сформулировать по-другому
Аналогию саму не понял. Может проблема не очень сформулирована. Я — разработчки. Я пишу комментарии в коде, мне так жить хорошо. Ко мне приходит писатель, который говорит, мол ему и его команде не удобно, не кофмортно идти в код, чтобы править комментарии. Из этих комментариев генерируется документация. Мне интересно, это у мне что-то не так или это проблема у кого-то уже встерчалась.
Конечно встречалась. Я думаю вопрос может звучать так: Есть ли какой-то инструмент, который принимает на вход код, а на выходе даёт какую-нибудь вики-лайк систему, в которой удобный интерфейс, и можно править описание параметров руками и сохранять по кнопке Сохранить. Потому что мы не умеем пользоваться гитом. Такие системы скорее всего уже есть, но я лично сталкивалась только с самописными. То есть ребята разработчики садятся и пишут, сами для себя.
Вооот. Я тоже к такой системе в своей голове пришел. Но так как я также ни разу не встречал подобных решения, смутился, а существует ли вообще такая система.
так-то это довольно простая мысль же, она не нам с вами первым в голову пришла, у всех есть проблема, что надо быстро проревьюить доку, а редактор или даже продакт оунер не умеет в гит но можно ли готовую просто так взять и купить, я не подскажу. вот здесь могут знать: Спросите https://t.me/docsascode
#практики #инструменты #docsascode
В прошлой компании столкнулись с таким. В итоге научили редакторов и техписателей пользоваться гитом, для всех сделали понятные инструкции, вся писательско-корректорская работа перешла в гитлаб.
Здравствуйте! А можете, пожалуйста, поделиться инструкциями? Интересно было бы почитать
Тут, действительно, лучше понять, что именно дискомфорт вызывает. Если неудобно комитить в исходный код, то можно, например, отдельный репозиторий для документации сделать. Чтобы не было конфликтов с МРами разработки. Но это просто как пример)
Да там инструкции как пуллить, пушить, мержить, по-минимуму, без дебрей. Скинуть не могу, потому что в той компании пару лет как не работаю
там вроде речь о том идёт чтобы вообще никогда в гит не ходить и код в глаза не видеть
Если так, то лучше донести до техписов ценность работы с кодом.) Это же полезный навык для роста, как специалиста.
моя команда делала как раз для гитлаба, как раз для связки техписателей+редакторов. сильно буксовали на моменте «обсудить в комментах» понятно что редактор привык к гуглодокам и хочет видеть просто веточку комментариев рядом с аккуратным листом бумаги, а не вот это вот всё что в гитлабе была такая пробема у вас?
Если бы всё было так просто в этом мире.
да нет, показали, что можно выделить конкретную строчку, нажать плюсик и прокомментировать эту строчку. Или можно сразу готовую правку предложить. Это простые инструменты, надо о них просто рассказать. Все дружно ими пользовались. Не с первого раза, но вскоре все вникли и привыкли
донести не сложно - не боишься Git - ведущий техпис, боишься - ну сиди исключительно на интерфейсах дальше на более низкой ставке
Я такую систему писал когда-то но не доделал - уволился.
про одну правку понятно, я именно про ветвление беседы к этой правке
А тут как удобно. Помню один редактор не любил в комментах болтать, ему проще было обсудить быстро интерактивно в мессенжере. Многим такой подход тоже казался продуктивным. Можно давать ссылки на конкретные строчки при обсуждении, это удобно
поняла. мне самой неудобно было в гитлабе работать с большими ветками комментариев, когда я вычитывала доку я привыкла конечно, но не скажу что это прямо супер удобная вещь ради одной которой стоит заводить гитлаб
А писатели не могут прямо править доку, которая генерится из комментариев разработки?
Нельзя. Должен быть единственный источник правды. Если начать править текст после генерации, то он начнет расходиться с тем что в коде. Также встает вопрос, как быть при следующей генерации, вновь править те же куски?
Тут непонятно, почему источник документации – эта разработка, и почему писателям приходится править комменты. Разработка так ужасно пишет комменты? Можно попробовать шаблоны им дать. А если сами комментарии неправильные, то, ну, это ж ошибка в коде. Не должно такое правиться как баг?)
это абсолютно нормальная, и более того правильная ситуация в случае, когда мы говорим про справочники к api, библиотекам и так далее
В моём понимании, код всегда должен быть источником документации. Не должно быть так, что код зависит от документации. Код — это всегда первоистоник, как там будет написано, так в документации и будет отображено.
дать разработчику который получает 500к в секунду шаблон чтобы он правильно писал кавычки? или дать техпису за 180к доступ в код?
Ситуация: разработчик пишет комментарии, а писатель их потом дополняет? Или ситуация: разработчик пишет комментарии, а писатель их потом переписывает? Если второе, то это уже какая-то двойная работа)
Разработчик пишет комментарии, писатель потом приводит их к определенному виду. В случае, если непонятно, что подразумевалось, задаёт вопросы разработчику.
я как—то перед сдачей важного проекта на сертификацию вот как-то внезапно решила прогнать комменты на мат - ох, не зря я это решила сделать, как оказалось....
Не могу сказать, потому что мне напонятно, как писатели правят комментарии к коду)
тогда зачем вы консультируете Ивана?
Предложу ещё один вариант, подсмотренный в самом настоящем кровавом энтерпрайзе: дать техписам возможность править код, но только комментарии. А из них автоматически собирать документацию средствами типа того же Sphinx.
Выше привели пример. Вот другой. Итоговый продукт должен быть передан в англоговорящую команду, а оутстаф разработчики плохо говорят и пишут на английском. Технический писатель корректирует как грамматику, так и смысл написанного.
Да, вынести комменты, тоже отличный вариант. Правда это только страховка от «испортил нам сборку» а не решение проблемы Ивана. Потому что вот прямо совсем уж вынести в вики-лайк систему = то о чём мы выше говорили, то есть вики-лайк система поверх гита
Ой, извиняюсь) Иван, простите) Но мы как-то делали с разработкой что-то типа редполитики для комментов. Вполне неплохо получилось
редполитика для комментов — отличная и очень нужная вещь если она публичная, поделитесь)
Увы, внутреннее )
нет я не говорю про дублирование, как ты мог подумать. в твоем конкретном случае возможно да, вырезать из кода это зло. но я однажды всерьерз прорабатывала эту возможность, разные «кодовые базы» бывают, иногда есть потребность текст класть рядышком, в соседнем файле
Я по комменту подумал, что не тому человеку отвечал) Не, я думал, Иван ответит, что правят писатели: только оформление комментариев или прям переписывает их и вносит много новой инфы для конкретной документации. От этого уже отталкиваться по шаблону)
ещё есть проблемы с локализацией, именно кода, не готовой доки, ну чтобы иностранные разработчики не пугались когда внутрь полезут. тогда тоже приходит мысль что надо бы как-то что-то менять
Это из серии let lodka = "seledka"; ? Еще попадались статьи, как ищут создателей вирусов. Там иногда чуть ли не лингвистический анализ названий переменных делают, чтобы определить автора.
Мб вариант, писателям ревьювить код разработки и оставлять комментарии к МР с нужным текстом? Это если проблема именно с комитами, а не чтением кода.)
Хотя нет, про локализацию это я чушь несу, скорее всего уже можно в норм системы локализации прямо весь код запихнуть локализовать и всё.
да не, это скорее из серии «Арина пока не разбирается в локализации, но очень старается»
про создателей вирусов классная история! так и жду что будет фильм где злодей в конце сыпется на ёлочках в комментах
Мы недавно выпустили маленькую апишечку, документация генерится из кода с помощью Доксигена. Разработчики в основном писали комменты сами, но всё проходило через моё (техписателя) ревью в битбакете. Комментарии на русском и английском. Аналогично, всё, что я писала, проходило ревью разработчиков. Все остались довольны сотрудничеством
Ну да. Тупо мат в комментариях, как коллеги рассказывали.
Но ведь такая система противоречит идее единого источника. Получается у вас на проекте два источника истины — комментарии к коду и отредактированные комментарии к коду в вики. Если что-то изменится в коде, и разраб поправит комментарий, то в вики это никак не отобразится. Проще правда всех гиту научить, чем поддерживать такую систему актуальной. В идеальном мире разраб вносит изменения в код и сразу же создает тикет на доработку доки. При этом источником истины считается дока, а комменты к коду нужны для удобства разрабов. Генерить на их основе доку — это скользкая дорожка (в ад).
а поделитесь пожалуйста, была ли у вас в битбакете история с многочисленными обсуждениям правки которая бы кончилась ветвлением комментариев в которых все запутались? или там это хорошо работает? в гитлабе мне не нравится пока этот момент
Не противоречит, если правки, которые вносятся в вики, автоматически оформляются как PR в репозиторий. Только после их принятия, вики будет перегенерирована с внесенными изменениями.
речь идет о том, что и в обратную сторону должно работать
Такой истории не было, как-то быстро договаривались
Доксиджен ван лав, кстати. У вас на каком языке код?
C++ )) могу поделиться результатом, если интересно
интересно! поделитесь!
только чур с тегом сделано!
#сделано https://help.rengabim.com/stdl/ru/group_two-dimensional.html https://help.rengabim.com/stdl/en/group_two-dimensional.html вводные странички - md
а на выходе сразу html?
красивое
Ага, 404
прошу прощения, поменяла ссылки телеграм похоже их сократил
Отлично получилось, как мне кажется!) Молодчаги)
А такая странная навигация так и задумывалась или это из-за комментов кода в качестве исходников? И откуда картинки взялись, если это комменты?
ну вообще картинки же можно в маркдауне добавлять из файлов в репозитории
Навигация задумывалась с учетом особенностей инструмента. Doxygen позволяет ссылаться на картинки в комментариях
конкретно эти картинки в md
А можно как-то взглянуть на исходники, хоть в каком-нибудь виде? А то я не до конца понимаю, что было ДО, чтобы оценить насколько это приемлемо для результата ПОСЛЕ.
Ну нет, взглянуть на исходники никак нельзя
Вот здесь есть ссылки на примеры, которые можно получить доксигеном ) https://habr.com/ru/articles/252101/
и ещё у доксиджена хорошая документация! я по ней училась
Сильно плюсую. Doxygen прекрасен =)
Обсуждают сегодня