@factorized Можно поделиться определением документации с твоих лекций?
Мне оно прям помогло иначе взглянуть на проблему

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

У нас ТЗ Foliant'ом собирается, если конкретно

ТЗ - это как раз про документацию.
Но я хочу сначала посмотреть, какие флоу поддерживает фолиант

Комментирование, это немного узкое место

В процессе разработки ТЗ отлично Merge Request'ы в Gitlab'е это решают.
После - пока сложнее

Что вы включаете в понятие управления требованиями?

use cases, альтернативы для отдельных клиентов и т.п.
с активным обсуждением обычно

Почему на ваш взгляд это не документация?

Я перетащил нашу документацию с самописной обертки вокруг ruby markdown на foliant.

Почему вообще возник вопрос о перезде?

* код писал я, причем очень давно и никакого желания дальше его развивать не было
* то, как я генерировал PDF с помощью ruby prawn было мягко говоря по-спартански

По сравнению с mkdocs и прочими фолиант подкупил интеграцией с пандоком, очень важная штука: бесплатно из коробки top-level поддержка PDF.

Чего мне не хватало из коробки в фолианте?

1. переименовывания результирующих файлов из их понятных имен вида live/publish.md в ужасный SEO-транслит potokovaya-peredacha/publikaciya
2. редиректов с человеческих unix-имен на транслит
3. возможности понять, какой урл будет у этой же страницы на другом языке для иконки языка
4. выгрузка кусков конфига из английской документации на диск для автотестов (мы тестируем документацию) и вставка их в русский вариант
5. выгрузка кусков документации в json для вставки их в админку нашего продукта


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

С чем возникли проблемы:

1. рубийный маркдаун существенно вольготнее относится к верске, чем питонячий. Пришлось много текста править
2. после рубийной Nokogiri, парсить HTML регекспами в питоне очень грустно. Очень не хватает API по объектному доступу к AST markdown
3. есть некоторая путаница между слоями метаданных фолианта и mkdocs. Вообще хотелось бы чтобы это не было разными вещами
4. процессоры фолианта разрешают падать и идти дальше. Реалии авторов фолианта такие, что им важнее собрать хоть что-то, чем собрать всё корректно. Мне наоборот — ворнинг уже повод упасть и не собирать документацию.
5. Пришлось написать немало кода, который подправлял плохую верстку в наших 3 миллионах символов (280 тыс слов)


Чего отдельно понравилось:

1. глобальное пространство имен анкоров. Ссылаться на уникальное по проекту имя секции — бесценно.
2. упаковка картинок и прочих ассетов в webpack-стиле, это важно
3. ну и вообще то, что люди решили его опенсорснуть и довести до отчуждаемого состояния. Это круто.

Ну, я вижу разные процессы для работы с требованиями и для создания документации.
Может быть я не прав )

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

Гильдии в Plesk, Xsolla, Miro, РТ МИС и Сбере.

Ребята из разных компаний делятся опытом внутренних гильдий, то есть профессиональных сообществ. Только что сам начал смотреть, ничего не напишу в анонсе. Но гильдии — это отличная тема. У нас их аж несколько: QA, devops, frontend, backend, security, accessibility.

Судя по набору компаний, будет чертовски интересно. Рекомендую.

https://youtu.be/rCgXq1i4D9E

Ох, это вообще не про процесс разработки...

Конечно!

@kvaleev на заметку )

Вспомнилось
— это не флоу
— не чоу?
— не флоу

Максим, а можно я это прямо в канал репостну?

Это очень подробный и ценный отзыв

На пункт 2 в проблемах: а чего ты не взял BeautifulSoup4? Тот же Nokogiri.

Может не разобрался