Смотрите, как хорошо сделан фидбек в Тарантуле:
https://github.com/tarantool/doc/issues/1665

Максим Лапшин (Flussonic.com) написал подробный обзор @foliantdocs — комбайна для сборки и публикации документации в веб, PDF, конфлюенс и разные другие форматы. Доки Flussonic теперь собираются именно Фолиантом.

С разрешения автора публикую обзор здесь:

Я перетащил нашу документацию с самописной обертки вокруг 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. ну и вообще то, что люди решили его опенсорснуть и довести до отчуждаемого состояния. Это круто.

@maxlapshin а куда можно репортить баги в вашей доке? :)

Ну, клейкого желтого листочка явно не хватит :)

Пишите как вам удобнее, буду благодарен за обратную связь

Таня Фокина, UX-писатель из ЦФТ, рассказывает о своей профессии и решает задачки в канале @rishavant.

С Таней мы давно знакомы, вместе работали в переводческой артели «Надмозг» и в ПК конференции DocFactor. Таня шарит, так что канал я очень рекомендую.

Мне особенно понравился пост про то, как полезно выяснять задачу бизнеса. У писателя по-хорошему не должно быть задачи «написать текст», как и у плотника нет задачи  «поиспользовать молоток», а у хирурга «порезать скальпелем». Это всё инструменты, а не задачи.

https://t.me/rishavant/7

Спасибо )

Уии

Ноушн запускает доступ к API.

Готовимся к полному завоеванию Ноушном всего мира knowledge-sharing'а

https://www.notion.so/api-beta

НАКАНЕЦТА

А, это только бета wait list... Ладно, пока продлю подписку на dynalist

Ноушн настолько ужасно оптимизирован, что это особо не даст ничего. Вот когда с электрона на что-то другое переедут - тогда и можно будет в него заезжать

В чём конкретно, при каких обстоятельствах, выражается ужасная оптимизация?

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

Хм. Пользовался на маке и на айфоне, не замечал подобного.
Может дело ещё и в количестве заметок/данных, что может требовать больше времени для синхронизации.
Обычно использую стандартные Notes. Они несколько архаичнее Notion, но я как-то привык к ним больше, поэтому и ушёл от последних.
Как бы там ни было, лишний повод проверить.

А в notion все делается мышкой? Псевдо-разметки как в Confluence там нет?
Или можно делать сложную разметку с клавиатуры?
(Это я тьюториалы смотрю)

У них всё реализовано за счёт так называемых блоков.

Результат можно экспортировать в пдф, хтмл, мд.

По поводу мыши, вероятнее всего. Точно не вспомню. Давно не пользовался.

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

Ну вот не люблю я веб-приложения, что ж теперь::) Кому что, поэтому ноушн я забросил