Привет! TLDR

Пару месяцев назад я решала проблему — чем генерить документацию в PDF, если у тебя доку собирает MkDocs, который из коробки этого не умеет. Просила тут помощи и обещала здесь же отписаться, что пробовала, к какому решению пришла. Я начинающий автоматизатор, могу написать простенький скрипт на баше или питоне, не больше. В сторону генерации из HTML я сразу не пошла, так как там не одностраничный документ и CSS для меня это слишком сложно. Поэтому я смотрела конвертеры из Markdown в PDF.

Что я пробовала:

1. Конвертер https://hub.docker.com/r/fiware/md2pdf/. Мне с разбега даже hello world не дался, нужно разбираться в настройках. Если бы не помог @glu0n, я бы может и не справилась. Результат очень не очень внешне + не работает с кириллицей из коробки. Зато не нужно собирать всё в один файл, он это делает за вас, ему можно скормить тот же конфиг что уже есть в MkDocs.

2. Typora https://typora.io/. Самое простое и быстрое решение. Делает все через Pandoc, очень хорошо настроен шаблон, PDF получается эстетичный, правильно подсвечивает код. Можно скачать десктопное приложение. Cобственно я так и сделала, когда мне нужно было сделать PDF быстро. Минусы: все равно кое-чего не хватает например, в готовом PDF нет номеров страниц, нужно как-то собирать все md-файлы в один, ну и герерить придется руками (зато GUI).

3. Foliant https://github.com/foliant-docs. Самый серьезный инструмент, делает всё, что нужно. Тоже генерит через Pandoc. Тоже не нужно собирать ему один файл. Разобраться самостоятельно можно, есть документация, хотя мне все-таки потребовалась помощь создателей, но они слава богу отвечают в чате. Из коробки PDF у меня получился достаточно приличного качества. Но стало понятно, что если я хочу что-то поправить, то нужно будет самой настраивать шаблон, плюс Foliant по-моему нет смысла использовать только для сборки PDF, он не использует ваш конфиг MkDocs, использует свой конфиг с содержанием (foliant.yml). По-хорошему нужно делать сборку всех форматов доки Фолиантом.

4. Pandoc. Полный контроль над процессом, но настройка, самое сложное — LaTeX-шаблон. Ну и собирать все md-файлы в один тоже придется. Килограммы документации, и она неплохая.

Как я генерирую PDF в итоге:

Стало понятно что все равно придется настраивать LaTeX-шаблон. И надо склеить md-файлы в один. Так как я контрол-фрик, да и сборка html-документации в MkDocs у меня уже настроена, я не стала склеивать файлы сторонней тулзой. Я написала короткий Python-скрипт, который парсит YAML-конфиг MkDocs и собирает один md-файл. Этот один я скармливаю Pandoc. Использую --pdf-engine=xelatex. Обложку с названием документа дизайнер сделал в PDF и я ее приклеиваю в конце с помощью pdfunite. Осталось разобраться в туче параметров tex-шаблонов.

Агрессивный наброс на документацию и вполне адекватный ответ. https://github.com/valor-software/ngx-bootstrap/issues/5566

Пара отличных докладов с последнего Гипéрбатона (это такая конфа Яндекса про документацию).

Официальная позиция Программных комитетов Highload++ и других IT-конференций на претензии к Игорю Сысоеву.
Там и моя подпись есть.

Минутка UX-писательства. Вот это баннер про куки на culture.ru

А это тот же баннер на artlebedev.ru

TL;DR: чат DocOps за ноябрь

Лана Новикова собрала главное из чата DocOps-сообщества за ноябрь. Обсуждаемые темы, тезисы, полезные ссылки. Это очень круто, спасибо Лане.

https://teletype.in/@lananovikova/BJW5p0NAr

​​Нотификации

Когда-то публикация доки в Plesk выглядела так: мы заходили по SSH на сервер, запускали команды и читали логи. Если что-то ломалось, копипастили логи разработчикам.

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

И вот под конец года я наконец добавил нотификации в Slack. Теперь в одном канале будет видна вся картина: что сегодня опубликовали, какие changelog'и обновились, где вдруг сломалась сборка. Кажется, не хватает только сообщений из вновь опубликованных коммитов.

А как вы мониторите публикацию доки? Расскажите в @docsascode.

С Новым годом, друзья!
Записал небольшое поздравление для вас. :)

И ещё одно поздравление от нашего программного комитета: https://youtu.be/XWBkXfk6iZ0

Каналы про документацию и управление знаниями.

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

Неожиданно, первым будет не канал, а блог на Дзене.

IT-всячина глазами технического писателя (9 читателей).
Станислав пишет нечасто, но зато там целые истории про работу техписателя.

@getdocument (25).
Автор периодически постит ссылки на хорошие статьи и видео, иногда пишет о собственном опыте обучения, например про документирование API и книгу Docs like Code. (Имя автора знаю, но в канале оно не указано, так что не пишу).

@KnowledgeConfChannel (269). Канал KnowledgeConf — конференции про управление знаниями в IT.

@shut_up_and_write Shut up and write (370).
Мария хорошо пишет про документацию со стороны UX и пользовательских сценариев. В 2019м была серия постов со сравнением документации популярных продуктов сейчас и много лет назад. Особенно полезно, если вы пишете доки для не-разработчиков.

@the_know_all The Know All — Управление знаниями в IT (373).
Лана, с которой мы вместе работаем в ПК KnowledgeConf, ведёт канал про управление знаниями. Мой любимый пост — про Окно Джохари.

@techwriters Techwriter's Daily (390).
Анонимный автор или даже команда авторов внимательно следит за курсами и мероприятиями для техписателей, иногда пишет про инструменты и другие полезные штуки. Аноним, спасибо за репосты!

@technical_writing Technical Writing 101 (718).
Никита пишет про Markdown и генераторы статических сайтов, часто пробует новые инструменты, а ещё находит ссылки на дельные статьи на английском. Мне особенно понравились посты про диаграммы как код и линтер Vale. Ещё Никита — завсегдатай чата @docsascode.

@lovely_it_hell Уютный адочек (843)
Игорь, ещё один мой коллега по KnowledgeConf, пишет про управление разработкой в целом. Много постов про управление знаниями, онбординг сотрудников, рост и исследования.

На случай, если это куда-нибудь репостнут, добавлю себя.

@docops, DocOps (1796)
Николай, пишу про документацию как код и другие практики DocOps. Пропагандирую само это слово и всё хорошее, что за ним стоит. Помогаю делать конференцию KnowledgeConf. Поддерживаю техписательское сообщество по мере сил. Раньше организовывал митапы про документацию и в 2020м ещё буду.

Обновление от 2021 года:

@gostdoc, Документалист.ГОСТ.

Вы не ждали, а он появился, дайджест чатика за декабрь https://teletype.in/@lananovikova/rkQBPByeI

Добавил в подборку три локальных чата: Украина, Минск, Пермь. Присоединяйтесь :)

​​Контрастная тема в документации
Microsoft сделал в своей документации не только светлую и тёмную темы, но ещё и контрастную. Я впервые встречаю такое и это очень круто, потому что делает сайт доступным для людей с нарушениями зрения.

Вообще, у MS всегда было неплохо с accessibility (a11y, доступностью). Например, с незапамятных времён в Windows была экранная лупа, диктор и увеличенный вдвое интерфейс. Молодцы, ставят высокую планку для всей отрасли.

Лана шарит, читайте!

Я тут собрала все известные мне способы публикации из разметки в конфлуэнс в статейку, https://habr.com/ru/post/483898/ это чуть больше, чем я рассказывала на митапчике, так как sphinxcontribbuilder обновился 3 января и стал поддерживать много классных плюшек, типа джира фильтров, мат формул, нумерованных заголовков и т.д.

Ребята из Фланта рассказали, как собирают документацию с помощью werf. Это их инструмент для автоматизации сборки докер-образов. Отличный пример принципа "drink your own champagne".

https://habr.com/ru/company/flant/blog/478690/