Как сделать так, чтобы документация не болела?

Мы с Семёном @factorized провели сегодня митап про документацию на Highload++ Siberia. Поговорили о типичных проблемах разработки, которые можно решать с помощью документации. Конечно, всё законспектировали. Вот, держите: https://github.com/docops-hq/conf/blob/master/highload/19/siberia/docs.md

Если вы были на митапе или вам просто интересна эта тема — давайте общаться дальше, заходите в чат @docsascode.

А вот пара фотографий с митапа.

​​Из статьи Почему Интернет до сих пор онлайн?:

Протокол BGP — Border Gateway Protocol, впервые был описан в 1989 году двумя инженерами из IBM и Cisco Systems на трёх «салфетках» — листах формата А4. Эти «салфетки» до сих пор лежат в главном офисе Cisco Systems в Сан-Франциско как реликвия сетевого мира.

А вот фото этих документов, источник: https://twitter.com/kazumasaikuta/status/1121568522495123456

​​Курс по документированию 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.