Календарь конференций про документацию и технические коммуникации: https://keycontent.org/Calendar

За ссылку спасибо @SashP84

​​Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.

Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.

Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.

Книгу можно купить на сайте издательства. Приятного чтения!

Митап про документацию в Новосибирске.

Прямо в эту субботу сообщество Konveerum проводит митап про документацию. Место — Новосибирск, Академгородок. Трансляция будет, если вам не слабо начать смотреть её в семь утра по МСК. :)

Сообщество Konveerum — про приборостроение, так что и митап будет с акцентом на ГОСТ, госзаказчиков, и любимые ими форматы DOCX и PDF.

В программе три доклада:

— Алёна Чернышева из Uniscan Research расскажет про то, как компания переехала с MS Word на Atlassian Confluence, но всё равно продолжила использовать Word, и почему всё именно так. Вероятно, доклад будет расширением или продолжением статьи на Хабре.

— Илья Улеско из documentat.io расскажет про переезд c DOCX на reStructuredText. В этом случае получилось переехать полностью, так что теперь уже из исходников в reST генерируется HTML, PDF и DOCX. По словам Ильи, документ в 150 страниц собирается примерно за 20 секунд.

— Дмитрий Перепелин из Моспротекста расскажет про использование DITA XML для разработки конструкторской документации. Дмитрий сообщает, что наиболее востребован формат PDF, но ещё из DITA можно делать (X)HTML, DOCX и EPUB.

Регистрация тут: https://konveerum.ru/

SEO для документации.
Read the Docs опубликовали руководство по search engine optimization для документации. В отличие от руководств по SEO «вообще», в этом есть конкретные примеры разметки reStructuredText. Например, я ни разу не заполнял метаданные, а теперь буду:

 meta::
    :denoscription lang=en:
        Adding additional CSS or JavaScript files
        to your Sphinx documentation can let
        you customize the look and feel of your
        docs or add additional functionality.

Читать тут: https://docs.readthedocs.io/en/latest/guides/technical-docs-seo-guide.html

​​Не писать на слайдах мелким шрифтом, вот что делать!

pandoc умеет конвертировать DOCX в reST, Markdown или AsciiDoc вместе с изображениями:

 pandoc -f docx --extract-media images -t rst -o document.rst document.docx 
pandoc -f docx --extract-media images -t markdown -o document.md document.docx
pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx

Изображения будут в директории images. В любой разметке сразу будут правильные ссылки на них.

​​А я думал, это называется документация.

Аттракцион «почувствуй себя нубом».

Читаю в доке Jekyll про то, как использовать шаблоны Liquid прямо в исходниках страниц. Это помогает раскладывать структурированные данные в HTML и переиспользовать готовые блоки с помощью include. И это очень удобно.

В сотый раз грущу, что такое есть в Jekyll, Hugo, вообще где угодно, кроме Sphinx.

В отчаянии гуглю и первой ссылкой нахожу статью 2016 года, в которой Eric Holscher в десять строк кода на Python добавляет эту фичу в Sphinx.

Эрик, ну как я теперь с этим буду жить?

Докеризованный Pandoc и куча фильтров Pandoc для разных задач: https://github.com/pandocker

«А ещё у нас нет культуры документирования. Кто-нибудь, запишите это.»

JetBrains давно используют собственный инструмент для документации, а теперь хотят его опубликовать.

Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.

Трансляция Write the Docs Prague.

Сегодня и завтра в Праге проходит конференция Write the Docs.

Программа на сегодня, 16 сентября:

— The Super Effective Writing Process of Grammy-winning Artists

— How to write the perfect error message

— How to launch your startup with good docs

— Surprise! You're a designer now

— Documenting known unknowns

— Write the API docs before the API exists

— Disagree with “I Agree”. Enforcing better data privacy through the language of documentation

— Inclusive environments are just better: science says so

Есть бесплатная трансляция: https://www.writethedocs.org/conf/prague/2019/livestream/.

Documentation as bash history!

Попалась интересная статья про Infrastructure as code (IaC). Автор противопоставляет правильное IaC неправильному:

«Предположим, приходите вы на новый проект, а вам говорят: "у нас Infrastructure as Code". В реальности оказывается, Infrastructure as bash history или, например, Documentation as bash history.»

Ссылку увидел в @chiki_briki_it через @count0_digest — спасибо!

​​Сообщество Write the Docs на TeamLeadConf SPb.

Впереди TeamLeadConf SPb! Пока что я отдыхаю от конференций (т.е. просто работаю), а мои коллеги по сообществу Write the Docs придут. Приходите к ним на стенд с вашими вопросами про документацию.

Если хотите что-то обсудить заранее, приходите с вопросами в чат @docsascode.

Стенд будет выглядеть вот так:

Горжусь своими коллегами :)

​Есть вопросы по технической документации? Не знаете, какой выбрать инструмент или на кого возложить ответственность за документирование? Спросите на стенде DocOps.

Толковый пост о технических писателях: кто такие, что умеют, в чём польза.
https://news.1rj.ru/str/bor_64/94

​​Налоговая служба Украины написала документацию к своему электронному кабинету на Sphinx/reST. В сайте узнаётся тема Read the Docs, можно скачать PDF и EPUB. Я считаю, для госоргана это очень круто и современно.

https://cabinet.tax.gov.ua/help/intro.html

Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)

Доклады с Write the Docs meetup - Stockholm
https://www.youtube.com/playlist?list=PL26ma051UtkOo1HZ5lcMTKbJ5AQ31hkWr

Какие самые крутые changelog'и вы видели? А какие вы внимательно читаете перед каждым обновлением? От каких больше всего пользы?

Расскажите в @docsascode, а?