​​Курс по документированию REST API на русском языке.

Тут случилось что-то невероятное. Курс Тома Джонсона по документированию REST API переведён на русский язык. Денис Старков сделал это сам, один, за полгода работы.

Оригинальный Documenting APIs: A guide for technical writers and engineers — наверное, самый полный и полезный открытый курс по документированию. Он рассчитан на технических писателей, разработчиков и студентов. Для техписателей этот курс — точка входа в документирование кода и API, очень интересную область работы, за которую ещё и неплохо платят. Разработчики из этого курса научатся структурировать информацию и понятно описывать свой код и API.

Читайте переведённый курс по документированию REST API, рекомендуйте его коллегам, ставьте звёзды репозиторию. Шлите пуллреквесты с правками, наконец. :)

Можно ли превратить создание документации в процесс.

На конференции #CodeFestX мы проводили квартирник про DocOps и документацию в целом. Рассказывали, как внедрять хорошие практики и процессы документирования. Я делился опытом внедрения DocOps и работы над документацией в Plesk, а Семён — опытом своей компании documentat.io, которая аутсорсит разработку документации.

Смотрите видео, шлите обратную связь (@factorized и @nick_volynkin), пишите автотесты на доки. :)

https://www.youtube.com/watch?v=fMcyiVju9Tg

Инструкция к Palantir Gotham.
В сеть утекла техническая документация к сервису для поиска данных о гражданах, который использует полиция и спецслужбы США. Сервис называется Palantir Gotham. Документация конкретно пользовательская, писали не для отчётности. В начале документа — «шпаргалки», четкие пошаговые инструкции со скриншотами. Потом более подробные инструкции, описания конкретных элементов интерфейса и сценариев.

Документация в PDF и plain text: https://www.documentcloud.org/documents/6190005-PALANTIR-Guide.html
Исходная статья: https://www.vice.com/en_us/article/9kx4z8/revealed-this-is-palantirs-top-secret-user-manual-for-cops
Про статью узнал из поста в @addmeto.

Приходите обсуждать в чат @docsascode. Тема этически сложная, давайте обойдем стороной холивары о политике и обсудим именно артефакт документации.

Отличный пост про docs as code и конкретно Sphinx/reST.

Репост из чата @docsascode

Интереснейшая дискуссия о проблемах ведения доки к проектам
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