Интереснейшая дискуссия о проблемах ведения доки к проектам
https://twitter.com/rothgar/status/1151730253082980353?s=19

Ещё один пост про ретроспективы конференций в Plesk, на этот раз даже со скриншотами. Вообще это отчёт по #HighloadSiberia, о ретроспективах — в конце поста.

https://habr.com/ru/company/plesk/blog/460885/

DocOps-митап начинается с доклада о том, как вести репозиторий с документацией. Рассказывает Константин Валеев, сотрудник Ростелекома и один из авторов Foliant.

​​Классная идея, которую я только что узнал из доклада — это release notes для самой документации. Обновили раздел А, переписали документ Б. Обязательно попробую. Пока что у нас это только в сообщениях коммитов есть, но отдельный документ может быть интересен сам по себе.

Всё остальное из этого прекрасного списка мы (в docs.plesk.com) уже делаем сами и всем рекомендуем. :)

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

Отчётный ролик про нашу #knowledgeconf2019

KnowledgeConf — самый полезный эксперимент Онтико этого года, и сегодня мы хотим еще раз окунуться в ту атмосферу идеального knowledge sharing’а, которая царила на конференции.
Смотрим отчетный ролик и записи лучших докладов и вас приглашаем 📺

​​Угадайте, что имели в виду авторы вакансии?
Пишите в @docsascode.

​​Документация шаблонизатора Liquid — это просто песня.

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

Где задать вопрос, обсудить интересную тему или опубликовать вакансию? Давайте разберемся, а то я сам скоро запутаюсь.

Про документацию и инструментарий для неё, в частности про документацию как код — @docsascode, это чат канала DocOps.

Про документацию, правила и стиль, термины, работу с ГОСТ и госзаказчиками — @technicalwriters, чат сообщества технических писателей. Ещё туда можно кидать вакансии техписателей, с тегом #tw_wanted.

Управление знаниями, особенно в IT-компаниях — @KnowledgeConfTalks, чат конференции KnowledgeConf.

Управление знаниями в компаниях других отраслей — @kmrusnw. Там совсем другие масштабы и методы, но айтишечке всё равно есть чему поучиться у экспертов из кровавого энтерпрайза.

Перевод, локализация, интернационализация и в чем разница между этими словами — @localizer, чат переводчиков и всех причастных.

Тексты в интерфейсах — @meet_ux_txt, сообщество UX-писателей.

Есть отдельный чатик любителей AsciiDoctor — @asciidoctor.
Это такой легковесный язык разметки, альтернатива Markdown и reStructuredText.

Чаты стран и городов

Сообщество Write the Docs в Минске @wtd_minsk.

Чат техписателей Перми @prm_techwriters.

Ставьте важное вперёд.

Пишет Александр Парень (@SashP84):
Почитываю блоги про авицию. Один из действующих лётчиков разбирает и публикует всякие материалы по тем или иным моментам. Так вот, все помнят, что были две катастрофы Boeing 737MAX, там выяснилось, что была недоработка ПО, но в данном материале пилот отмечает, что оказывается на заметку "Note" в инструкциях никто не обращает внимания.
https://denokan.livejournal.com/207143.html

По ссылке обсуждают инструкцию к самолёту. В ней текст с такой структурой:

Сделайте А
Note: но если выполнено условие X, сначала сделайте Б, иначе случится что-нибудь плохое. (Сделать Б после А технически невозможно).

В критической ситуации человек читает и выполняет первую инструкцию, а потом уже находит вторую. Или не находит. Иногда это приводит к катастрофе.

Вывод автора блога: блок нужно называть Warning, а не Note, и ставить перед остальным текстом. Так у читателя будет меньше шансов пропустить этот блок и больше шансов спасти самолёт.

Не все пишут инструкции к самолётам, но правило-то работает везде. Важное — вперёд.

Три отличных расширения для Sphinx: панелька с предупреждением про версию, страница 404 и очень крутой тултип.

1. sphinx-version-warning: allows you to add a custom warning banner at the top of your documentation pages to communicate some important about this documentation: https://sphinx-version-warning.readthedocs.io

2. sphinx-notfound-page: is great to create a "Not found" (or 404) page to show when the reader hit a not found page: https://sphinx-notfound-page.readthedocs.io

3. sphinx-hoverxref: adds amazing tooltips on your cross-references that points to another page/section of the documentation including its content on the tooltip: https://sphinx-hoverxref.readthedocs.io

#python

Потратил час на то чтобы надёжно добавить CSS в проект на Sphinx. Придумал новую игру «код-конфиг-шаблон»:

— переменная конфига html_css_files бьёт редактирование шаблона layout.html в теме;
— вызов функции app.add_stylesheet бьёт переменную конфига;
— редактирование шаблона бьёт вызов функции.

Календарь конференций про документацию и технические коммуникации: 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::
    :description 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. В любой разметке сразу будут правильные ссылки на них.