Комментарии 7
Спасибо за статью! Интересно было прочитать как оно работает :)
А есть ли цели по генерации этих описаний автоматически из кода? Общеизвестное мнение среди инженеров, что конфлюенц это та ещё неудобная дрянь, и кажется что автоматический экспорт из README.md в корне репозитория повысил бы конверсию описываемости.
Когда человек уходит из компании, есть процедура пересмотра где в конфлюенц он был записан как ответственный за какой-то сервис? Или за это тоже отвечает совесть белковых тел?
А есть ли цели по генерации этих описаний автоматически из кода? Общеизвестное мнение среди инженеров, что конфлюенц это та ещё неудобная дрянь, и кажется что автоматический экспорт из README.md в корне репозитория повысил бы конверсию описываемости.
Когда человек уходит из компании, есть процедура пересмотра где в конфлюенц он был записан как ответственный за какой-то сервис? Или за это тоже отвечает совесть белковых тел?
Спасибо за вопросы.
По первому вопросу. А какие «эти описания»? Если ты говоришь про описание бизнес-процессов, то их сгенерировать из кода в человекопонятном виде невозможно, т.к. это человеческие истории. Да, мы автоматизируем эти бизнес-процессы. Но, во-первых, не все процессы автоматизированы, во-вторых, не все нюансы прописаны. Например, иногда нам важно понимать, откуда берутся шаблоны для заявлений возвратов. В коде такой информации не будет, т.к. это физические процессы.
Мы несколько раз обсуждали, как можно автоматизировать описание из кода. Но пока такого решения нет. Помимо описаний мы еще фиксируем спецификации по проектам, чек-листы и это также уже не автоматизировать, поэтому шаблоны в любом случае никуда не денутся.
По второму вопросу, к сожалению, такого централизованного процесса нет. Все зависит от конкретного сервиса. Например, в Commercial-направлении есть аналитики, которые отвечают за документацию и там обязательно проговариваем, а кто после их ухода будет за это отвечать. Аналогично, есть по фронтовой части.
По первому вопросу. А какие «эти описания»? Если ты говоришь про описание бизнес-процессов, то их сгенерировать из кода в человекопонятном виде невозможно, т.к. это человеческие истории. Да, мы автоматизируем эти бизнес-процессы. Но, во-первых, не все процессы автоматизированы, во-вторых, не все нюансы прописаны. Например, иногда нам важно понимать, откуда берутся шаблоны для заявлений возвратов. В коде такой информации не будет, т.к. это физические процессы.
Мы несколько раз обсуждали, как можно автоматизировать описание из кода. Но пока такого решения нет. Помимо описаний мы еще фиксируем спецификации по проектам, чек-листы и это также уже не автоматизировать, поэтому шаблоны в любом случае никуда не денутся.
По второму вопросу, к сожалению, такого централизованного процесса нет. Все зависит от конкретного сервиса. Например, в Commercial-направлении есть аналитики, которые отвечают за документацию и там обязательно проговариваем, а кто после их ухода будет за это отвечать. Аналогично, есть по фронтовой части.
Ненене, я не говорю про генерацию описаний автоматически из кода сервиса.
Описание человеческих историй может быть в markdown в виде
```
### Истории
* история 1, «простая»: человек идёт туда-то и получает такой-то токен
* история 2, «сложная»: полученный токен протух и человек получает новый
```
То есть не идёт речь о парсинге таких описаний прямо из кода приложения, а просто их загрузка из отдельного файла хранящегося в том же репозитории (я верю что разработчики будут чаще следить за файлом рядом с кодом, особенно если это где-то прописано в процессах, чем ходить на веб-страницу в редакторе унизительно мышкой кликать). Ну то есть просто чтобы не ходить ради этого на страницу confluence и пользоваться его интерфейсом.
Описание человеческих историй может быть в markdown в виде
```
### Истории
* история 1, «простая»: человек идёт туда-то и получает такой-то токен
* история 2, «сложная»: полученный токен протух и человек получает новый
```
То есть не идёт речь о парсинге таких описаний прямо из кода приложения, а просто их загрузка из отдельного файла хранящегося в том же репозитории (я верю что разработчики будут чаще следить за файлом рядом с кодом, особенно если это где-то прописано в процессах, чем ходить на веб-страницу в редакторе унизительно мышкой кликать). Ну то есть просто чтобы не ходить ради этого на страницу confluence и пользоваться его интерфейсом.
Это реально, мы часть инфы для конфли генерили из кода. Но это работает только для тех мест, которые поддерживает разработка. Пустить в репозиторий аналитиков\бизнес\саппорт может быть немного геморно со всех сторон (для одних — тюнинг прав и больше нагрузка на ревью изменений в репе, для других — необходимость изучать гит и процессы по которым это попадает в финальную доку, как посмотреть промежуточный результат без коммита и т.ж.)
Да, согласна. Есть такое опыт в некоторых компаниях и по отзывам весьма неплох. Он помогает даже автоматизировать тесты. Но все равно остается много деталей и нюансов. Например, хочется в одном месте видеть сводную таблицу, кто и в каких системах может создавать заказ, какие есть особенности у каждого создания. Это в таких сценариях не создать, чтобы было легко читаемым.
Также очень помогают не расписанные текстом сценарии, а схемы, т.к. они визуализируют процессы и разработчики их проще воспринимают. Поэтому микс в любом случае будет получаться.
Также очень помогают не расписанные текстом сценарии, а схемы, т.к. они визуализируют процессы и разработчики их проще воспринимают. Поэтому микс в любом случае будет получаться.
Спасибо, этого очень не хватало — подтолкнули от бесполезного «надо что-то делать» к «давайте уже обсудим шаблоны и внедрим с нашими доработками».
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Как создать шаблон описания системы и начать его использовать