Есть такое понятие как "good enough docs" - необязательно делать идеальную документацию, главное, чтобы она достаточно хорошо выполняла задачу. Это дает гибкость, поскольку "хорошо" каждый определяет сам, сообразно своему продукту

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

А вы сами работали на госпроектах?
Я работал. Там нет водопада. Там нормальный процесс внесения изменений в проект при необходимости и итерации (этапы разработки)

Подтверждаю

Всем привет. Кто-нибудь Marked2 пользовался?

Пожалуйста :)

Никак) они просто забывают.

Там, кстати, уже несколько контрибьюторов. Например, ещё @koshatneg и @b0g3r.

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

Исходные данные - ранее в компании документация не велась. Какими инструментами задокументировать код, разработчики примерно представляют. Остается вопрос о документации разных бизнес-процессов, чек-листов, инфраструтктуры и прочего.

Пара техрайтеров. Гугл доки. При желании какой-то knowledge base, мы выбрали bookstack

вот тут можно порыться https://events.yandex.ru/events/hyperbaton/

Благодарю

На конфе в Праге заявлен доклад The UK government meets docs as code

Всем привет!

Перед моей командой сечас стоит задача по синхронизации описания задач и систем/продуктов. Наверняка, кто-то уже решал ее, поделитесь, плз, опытом или материалами.

Суть проблемы:
- Существует описание продукта или системы. Пользователи, бизнес-процессы, фичи.
- Описание задачи, которое формируется в процессе разработки новой фичи. В него включены видение бизнеса, требования, ит архитектура, техническое описание от разрабов и тестовые сценарии

После того, как фича реализована, нужно обновить исходное описание продукта, включив в него описание фичи. Разные подходы содают различные проблемы:
- Вести описание продукта и задач раздельно, а потом обновлять описание продукта неудобно, т.к. возникает потребность в осмысленном мердже фичей в описание продукт. Плюс сразу несколько человек могут описывать разные изменения в одном функционале.
- Вести описание нового функционала сразу в описании продукта. Минусы: со стороны сложно определить, какой функционал в разработке, какой уже существуют; при параллельной разработке нескольких фичей, они могут пересекаться в описании.
- Вести описание в гите. Минусы: нетривиальный мердж ветки с описанием фичи в основную, не все пользователи (например, бизнес) умеют пользоваться гитлабом

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

Т.е. описание системы отдельно, фичи отдельно, после завершения разработки мерджим в описание продукта?

да

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

не очень удобно поддерживать