Похожие чаты

Привет писатели. Расскажите, пожалуйста, как у вас выстроено общение с

разработчками.

В наличии кодовая база на языке N. Комментарии к сигнатурам и есть документация. Проблема в том, что для разработчиков такое положение удобно, для писателей — нет. Им не нравится идти в исходный код чтобы править документацию. Сталкиваетесь ли вы с подобным? Если да, то как решали или какие подходы у вас в целом были?

85 ответов

48 просмотров

Сталкивались. Генерация документации из кода + техписатели которые способны контрибьютить прямо в код, в системе контроля версий конечно же.

Arina Ballerina
Сталкивались. Генерация документации из кода + тех...

тут условие как я понял что техписам неудобненько) я бы их на мороз отправил, а остальные пусть учатся коммиты делать)

Dmitriy
тут условие как я понял что техписам неудобненько)...

я не понимаю как может быть неудобненько когда генерируется готовый справочник на 500+ страниц

Ivan-Uhalin Автор вопроса
Arina Ballerina
я не понимаю как может быть неудобненько когда ген...

Под неудобно я имел ввиду делать коммиты в исходный код.

Ivan Uhalin
Под неудобно я имел ввиду делать коммиты в исходны...

поймите меня правильно: неудобно, пока нет профитов. и я не премию имею в виду профит это когда руководитель предложил мне сравнить ситуацию 1: в которой я, техпис, правлю тип данных сам руками, в табличке в конфлюенсе и ситуацию2: в которой я, техпис, ничего не правлю оно само правится

На одном из проектов разработчики писали комментарии, а мы, писатели, их редактировали. Затем из комментов собирали доку. Подучились, пообщались с разработчиками и вперед. Это просто была одна из базовых задач писателей.

Ivan-Uhalin Автор вопроса
Ivan Uhalin
Не понял.

что именно? я попробую сформулировать по-другому

Ivan-Uhalin Автор вопроса
Arina Ballerina
что именно? я попробую сформулировать по-другому

Аналогию саму не понял. Может проблема не очень сформулирована. Я — разработчки. Я пишу комментарии в коде, мне так жить хорошо. Ко мне приходит писатель, который говорит, мол ему и его команде не удобно, не кофмортно идти в код, чтобы править комментарии. Из этих комментариев генерируется документация. Мне интересно, это у мне что-то не так или это проблема у кого-то уже встерчалась.

Ivan Uhalin
Аналогию саму не понял. Может проблема не очень сф...

Конечно встречалась. Я думаю вопрос может звучать так: Есть ли какой-то инструмент, который принимает на вход код, а на выходе даёт какую-нибудь вики-лайк систему, в которой удобный интерфейс, и можно править описание параметров руками и сохранять по кнопке Сохранить. Потому что мы не умеем пользоваться гитом. Такие системы скорее всего уже есть, но я лично сталкивалась только с самописными. То есть ребята разработчики садятся и пишут, сами для себя.

Ivan-Uhalin Автор вопроса

Вооот. Я тоже к такой системе в своей голове пришел. Но так как я также ни разу не встречал подобных решения, смутился, а существует ли вообще такая система.

Ivan Uhalin
Вооот. Я тоже к такой системе в своей голове прише...

так-то это довольно простая мысль же, она не нам с вами первым в голову пришла, у всех есть проблема, что надо быстро проревьюить доку, а редактор или даже продакт оунер не умеет в гит но можно ли готовую просто так взять и купить, я не подскажу. вот здесь могут знать: Спросите https://t.me/docsascode

#практики #инструменты #docsascode

Ivan Uhalin
Аналогию саму не понял. Может проблема не очень сф...

В прошлой компании столкнулись с таким. В итоге научили редакторов и техписателей пользоваться гитом, для всех сделали понятные инструкции, вся писательско-корректорская работа перешла в гитлаб.

Lex
В прошлой компании столкнулись с таким. В итоге на...

Здравствуйте! А можете, пожалуйста, поделиться инструкциями? Интересно было бы почитать

Ivan Uhalin
Аналогию саму не понял. Может проблема не очень сф...

Тут, действительно, лучше понять, что именно дискомфорт вызывает. Если неудобно комитить в исходный код, то можно, например, отдельный репозиторий для документации сделать. Чтобы не было конфликтов с МРами разработки. Но это просто как пример)

Evdoxy
Здравствуйте! А можете, пожалуйста, поделиться инс...

Да там инструкции как пуллить, пушить, мержить, по-минимуму, без дебрей. Скинуть не могу, потому что в той компании пару лет как не работаю

Виктор Орлов
Тут, действительно, лучше понять, что именно диско...

там вроде речь о том идёт чтобы вообще никогда в гит не ходить и код в глаза не видеть

Arina Ballerina
там вроде речь о том идёт чтобы вообще никогда в г...

Если так, то лучше донести до техписов ценность работы с кодом.) Это же полезный навык для роста, как специалиста.

Lex
Да там инструкции как пуллить, пушить, мержить, по...

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

Ivan-Uhalin Автор вопроса
Arina Ballerina
моя команда делала как раз для гитлаба, как раз дл...

да нет, показали, что можно выделить конкретную строчку, нажать плюсик и прокомментировать эту строчку. Или можно сразу готовую правку предложить. Это простые инструменты, надо о них просто рассказать. Все дружно ими пользовались. Не с первого раза, но вскоре все вникли и привыкли

Ivan Uhalin
Если бы всё было так просто в этом мире.

донести не сложно - не боишься Git - ведущий техпис, боишься - ну сиди исключительно на интерфейсах дальше на более низкой ставке

Arina Ballerina
Конечно встречалась. Я думаю вопрос может звучать ...

Я такую систему писал когда-то но не доделал - уволился.

Lex
да нет, показали, что можно выделить конкретную ст...

про одну правку понятно, я именно про ветвление беседы к этой правке

Arina Ballerina
про одну правку понятно, я именно про ветвление бе...

А тут как удобно. Помню один редактор не любил в комментах болтать, ему проще было обсудить быстро интерактивно в мессенжере. Многим такой подход тоже казался продуктивным. Можно давать ссылки на конкретные строчки при обсуждении, это удобно

Lex
А тут как удобно. Помню один редактор не любил в к...

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

Ivan Uhalin
Если бы всё было так просто в этом мире.

А писатели не могут прямо править доку, которая генерится из комментариев разработки?

Ivan-Uhalin Автор вопроса
Виктор Орлов
А писатели не могут прямо править доку, которая ге...

Нельзя. Должен быть единственный источник правды. Если начать править текст после генерации, то он начнет расходиться с тем что в коде. Также встает вопрос, как быть при следующей генерации, вновь править те же куски?

Ivan Uhalin
Нельзя. Должен быть единственный источник правды. ...

Тут непонятно, почему источник документации – эта разработка, и почему писателям приходится править комменты. Разработка так ужасно пишет комменты? Можно попробовать шаблоны им дать. А если сами комментарии неправильные, то, ну, это ж ошибка в коде. Не должно такое правиться как баг?)

Виктор Орлов
Тут непонятно, почему источник документации – эта ...

это абсолютно нормальная, и более того правильная ситуация в случае, когда мы говорим про справочники к api, библиотекам и так далее

Ivan-Uhalin Автор вопроса
Виктор Орлов
Тут непонятно, почему источник документации – эта ...

В моём понимании, код всегда должен быть источником документации. Не должно быть так, что код зависит от документации. Код — это всегда первоистоник, как там будет написано, так в документации и будет отображено.

Виктор Орлов
Тут непонятно, почему источник документации – эта ...

дать разработчику который получает 500к в секунду шаблон чтобы он правильно писал кавычки? или дать техпису за 180к доступ в код?

Ситуация: разработчик пишет комментарии, а писатель их потом дополняет? Или ситуация: разработчик пишет комментарии, а писатель их потом переписывает? Если второе, то это уже какая-то двойная работа)

Виктор Орлов
Ситуация: разработчик пишет комментарии, а писател...

Разработчик пишет комментарии, писатель потом приводит их к определенному виду. В случае, если непонятно, что подразумевалось, задаёт вопросы разработчику.

Виктор Орлов
Ситуация: разработчик пишет комментарии, а писател...

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

Не могу сказать, потому что мне напонятно, как писатели правят комментарии к коду)

Arina Ballerina
дать разработчику который получает 500к в секунду ...

Предложу ещё один вариант, подсмотренный в самом настоящем кровавом энтерпрайзе: дать техписам возможность править код, но только комментарии. А из них автоматически собирать документацию средствами типа того же Sphinx.

Ivan-Uhalin Автор вопроса
Виктор Орлов
Не могу сказать, потому что мне напонятно, как пис...

Выше привели пример. Вот другой. Итоговый продукт должен быть передан в англоговорящую команду, а оутстаф разработчики плохо говорят и пишут на английском. Технический писатель корректирует как грамматику, так и смысл написанного.

Максим Дунаевский
Предложу ещё один вариант, подсмотренный в самом н...

Да, вынести комменты, тоже отличный вариант. Правда это только страховка от «испортил нам сборку» а не решение проблемы Ивана. Потому что вот прямо совсем уж вынести в вики-лайк систему = то о чём мы выше говорили, то есть вики-лайк система поверх гита

Arina Ballerina
тогда зачем вы консультируете Ивана?

Ой, извиняюсь) Иван, простите) Но мы как-то делали с разработкой что-то типа редполитики для комментов. Вполне неплохо получилось

Виктор Орлов
Ой, извиняюсь) Иван, простите) Но мы как-то делал...

редполитика для комментов — отличная и очень нужная вещь если она публичная, поделитесь)

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

Arina Ballerina
тогда зачем вы консультируете Ивана?

Я по комменту подумал, что не тому человеку отвечал) Не, я думал, Иван ответит, что правят писатели: только оформление комментариев или прям переписывает их и вносит много новой инфы для конкретной документации. От этого уже отталкиваться по шаблону)

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

Arina Ballerina
ещё есть проблемы с локализацией, именно кода, не ...

Это из серии let lodka = "seledka"; ? Еще попадались статьи, как ищут создателей вирусов. Там иногда чуть ли не лингвистический анализ названий переменных делают, чтобы определить автора.

Ivan Uhalin
Выше привели пример. Вот другой. Итоговый продукт ...

Мб вариант, писателям ревьювить код разработки и оставлять комментарии к МР с нужным текстом? Это если проблема именно с комитами, а не чтением кода.)

Arina Ballerina
ещё есть проблемы с локализацией, именно кода, не ...

Хотя нет, про локализацию это я чушь несу, скорее всего уже можно в норм системы локализации прямо весь код запихнуть локализовать и всё.

Ed P
Это из серии let lodka = "seledka"; ? Еще попадал...

да не, это скорее из серии «Арина пока не разбирается в локализации, но очень старается»

Ed P
Это из серии let lodka = "seledka"; ? Еще попадал...

про создателей вирусов классная история! так и жду что будет фильм где злодей в конце сыпется на ёлочках в комментах

Мы недавно выпустили маленькую апишечку, документация генерится из кода с помощью Доксигена. Разработчики в основном писали комменты сами, но всё проходило через моё (техписателя) ревью в битбакете. Комментарии на русском и английском. Аналогично, всё, что я писала, проходило ревью разработчиков. Все остались довольны сотрудничеством

Ed P
Это из серии let lodka = "seledka"; ? Еще попадал...

Ну да. Тупо мат в комментариях, как коллеги рассказывали.

Ivan Uhalin
Вооот. Я тоже к такой системе в своей голове прише...

Но ведь такая система противоречит идее единого источника. Получается у вас на проекте два источника истины — комментарии к коду и отредактированные комментарии к коду в вики. Если что-то изменится в коде, и разраб поправит комментарий, то в вики это никак не отобразится. Проще правда всех гиту научить, чем поддерживать такую систему актуальной. В идеальном мире разраб вносит изменения в код и сразу же создает тикет на доработку доки. При этом источником истины считается дока, а комменты к коду нужны для удобства разрабов. Генерить на их основе доку — это скользкая дорожка (в ад).

Asya Tyan
Мы недавно выпустили маленькую апишечку, документа...

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

Ivan-Uhalin Автор вопроса
Константин Макушев
Но ведь такая система противоречит идее единого ис...

Не противоречит, если правки, которые вносятся в вики, автоматически оформляются как PR в репозиторий. Только после их принятия, вики будет перегенерирована с внесенными изменениями.

Константин Макушев
Но ведь такая система противоречит идее единого ис...

речь идет о том, что и в обратную сторону должно работать

Arina Ballerina
а поделитесь пожалуйста, была ли у вас в битбакете...

Такой истории не было, как-то быстро договаривались

Asya Tyan
Такой истории не было, как-то быстро договаривалис...

Доксиджен ван лав, кстати. У вас на каком языке код?

Arina Ballerina
Доксиджен ван лав, кстати. У вас на каком языке ко...

C++ )) могу поделиться результатом, если интересно

#сделано https://help.rengabim.com/stdl/ru/group_two-dimensional.html https://help.rengabim.com/stdl/en/group_two-dimensional.html вводные странички - md

Asya Tyan
да

красивое

Ed P
screenshot Хм....

Ага, 404

Алексей Таразанов
Ага, 404

прошу прощения, поменяла ссылки телеграм похоже их сократил

Asya Tyan
#сделано https://help.rengabim.com/stdl/ru/group_...

Отлично получилось, как мне кажется!) Молодчаги)

Asya Tyan
#сделано https://help.rengabim.com/stdl/ru/group_...

А такая странная навигация так и задумывалась или это из-за комментов кода в качестве исходников? И откуда картинки взялись, если это комменты?

rJIynbIu` KOT
А такая странная навигация так и задумывалась или ...

ну вообще картинки же можно в маркдауне добавлять из файлов в репозитории

rJIynbIu` KOT
А такая странная навигация так и задумывалась или ...

Навигация задумывалась с учетом особенностей инструмента. Doxygen позволяет ссылаться на картинки в комментариях

Asya Tyan
Навигация задумывалась с учетом особенностей инстр...

А можно как-то взглянуть на исходники, хоть в каком-нибудь виде? А то я не до конца понимаю, что было ДО, чтобы оценить насколько это приемлемо для результата ПОСЛЕ.

rJIynbIu` KOT
А можно как-то взглянуть на исходники, хоть в како...

Ну нет, взглянуть на исходники никак нельзя

Asya Tyan
Ну нет, взглянуть на исходники никак нельзя

Вот здесь есть ссылки на примеры, которые можно получить доксигеном ) https://habr.com/ru/articles/252101/

Asya Tyan
Вот здесь есть ссылки на примеры, которые можно по...

и ещё у доксиджена хорошая документация! я по ней училась

Похожие вопросы

Обсуждают сегодня

А кто-то пробовал, уезжая из Эстонии получить э-рез и продолжить вести предпринимательскую деятельность внутри Эстонии, используя свой OÜ?
Lalalashechki Lalala
57
@MrMiscipitlick А можешь макрос написать, который будет вычислять смещение относительно переданных меток? Просто .label1-.label2, и вернуть значение.
КТ315
35
@samkazemian - couple questions: Update on frxBTC? - This would do well with the current influx of institutional investment entering the space Update on future veFXS streams...
Costi
16
я не магистр хаскеля, но разве не может лейзи тип конвертнуться в не-лейзи запросив вычисление содержимого прям при инициализации?
deadgnom32 λ madao
100
А еще в перле можно уже @arr1 + @arr2?
Sergei Zhmylove
53
Does anyone here have a connection Mullvad? it would be nice to know what it would take to have them accept BCH 0-conf.
tl121x
16
Подобного рода ;Следующие три строки это директивы ассемблера, ;которые можно не задавать, т.к.работаем в Visual Studio. ;Символ ";" - это начало однострочного комментария ...
Егор Анелькин
3
Can an XMR transaction be tracked from its sender to its receiver by performing blockchain analysis, no matter how many addresses are used?
Trkz342
16
Кто-нибудь знает почему SPM клонирует репо целиком? Некоторые репы просто огромные, как та же swift-syntax которая нужна для использования макросов. Сначала подумал, что это...
iMike
6
I arrived here after a Chico Crypto show highlighted the project & the Team - the fact that the Team had a long history of successfully working with household names gave me e...
Banter is Bullish
5
Карта сайта