DocOps

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

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

Ещё один пост про ретроспективы конференций в Plesk, на этот раз даже со скриншотами. Вообще это отчёт по #HighloadSiberia, о ретроспективах — в конце поста. https://habr.com/ru/company/plesk/blog/460885/

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

Коллеги, хотел бы поделиться с вами своей статьей на тему автоматизации процесса сборки сайта с документацией. Это мой первый опыт как полноценной работы в роли технического писателя, так и в написании подобного рода статей, буду рад критике! https://habr.com/ru/company/youla/blog/459640/

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

Инструкция к 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. Тема этически сложная, давайте обойдем стороной холивары о политике и обсудим именно артефакт документации.

Можно ли превратить создание документации в процесс. На конференции #CodeFestX мы проводили квартирник про DocOps и документацию в целом. Рассказывали, как внедрять хорошие практики и процессы документирования. Я делился опытом внедрения DocOps и работы над документацией в Plesk, а Семён — опытом своей компании documentat.io, которая аутсорсит разработку документации. Смотрите видео, шлите обратную связь (@factorized и @nick_volynkin), пишите автотесты на доки. :) https://www.youtube.com/watch?v=fMcyiVju9Tg

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

​​Из статьи Почему Интернет до сих пор онлайн?: Протокол BGP — Border Gateway Protocol, впервые был описан в 1989 году двумя инженерами из IBM и Cisco Systems на трёх «салфетках» — листах формата А4. Эти «салфетки» до сих пор лежат в главном офисе Cisco Systems в Сан-Франциско как реликвия сетевого мира. А вот фото этих документов, источник: https://twitter.com/kazumasaikuta/status/1121568522495123456

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

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

Поводом к спору послужил наш с Семёном Факторовичем и Евгением Галактионовым квартирник на #CodeFestX. Мы там говорили о профессиях аналитика и технического писателя, ожиданиях, требованиях и зоне ответственности. А ещё у меня там половину времени очень странное выражение лица. Так уж получилось :) https://youtu.be/h48ycbRFDsU

У нас тут возник спор о профессиях и ролях. Одни не берут на себя лишних ролей и задач, потому что за них всё равно не доплачивают. Другие выходят за рамки профессии и роли, и договариваются о более высокой зарплате. А у вас как?

Highload++ Siberia. Мы с коллегами по сообществу Write the Docs снова идём на конференцию Highload++ Siberia. Если вы там будете — заходите к нам на стенд поговорить про документацию и управление знаниями. Организаторы конференции — ребята щедрые и гостеприимные. Они дарят скидку 50% на билет всем участникам, которые платят сами за себя по промокоду Personal{DocOps}. Если вы студент или преподаватель, то для вас скидка целых 75%, промокод Academic{DocOps}. Вот сообщение от самих организаторов. HighLoad++ Siberia 2019 – Профессиональная конференция разработчиков высоконагруженных систем. 24 и 25 июня 2019г. в Экспоцентре, Новосибирск, пройдет конференция для разработчиков highload-систем, которая соберёт 600 участников из разных регионов России и мира. Мероприятие направлено на обмен знаниями о технологиях, позволяющих одновременно обслуживать многие тысячи и миллионы пользователей. Мы решили расширить аудиторию конференции Highload++ Siberia и предлагаем две новые возможности для участия: + Если вы студент, аспирант или преподаватель ВУЗа, то вы можете воспользоваться скидкой в 75% от стоимости билета - используйте скидочный код Academic{DocOps} при заказе билетов на сайте конференции. Имейте в виду, что при регистрации мы попросим вас показать любой документ, удостоверяющий ваш статус." + Если вы частное лицо и нет компании, которая компенсировала бы вам билет, то вы можете воспользоваться скидкой в 50% - используйте скидочный код Personal{DocOps}. В обоих случаях оплата возможна только как оплата от частного лица через Яндекс.Кассу и вы можете заказать билет только для себя. Впрочем вы можете передать скидочный код вашему сокурснику или другу и он может сделать то же самое. Надеемся, что вам у нас понравится 😊

Документация ≠ текст. Осенью 2015 года я работал тестировщиком в 2ГИС и только начинал разбираться с Ansible. Читал наши ansible-скрипты, но ничего не понимал. Читал документацию и туториалы на docs.ansible.com, и тоже ничего не понимал. Чувствовал себя нубом. А потом я посмотрел видео, где Джефф Гирлинг показывает простые ad-hoc команды на стеке из шести «малинок» (Raspberry Pi). И после этого смог выполнить эти же команды на своем тестовом хосте. А потом и всё остальное понял, и с удовольствием драйвил тему Ansible в команде, пока не уволился. К чему это я. Документация — это не только текст. Есть другие способы донести до читателя технические знания: видео, схемы, гифки, выступление на конференции, подкаст. Они могут работать гораздо лучше, чем текст. Вот то самое видео: https://youtu.be/ZNB1at8mJWY

​​В русской википедии утверждается, что «наглядная работа алгоритма показана на рисунке» и дальше вот этот рисунок. Диплом о высшем математическом образовании дает мне силы сказать: это картинка не наглядная, а не мы тупые. Не корите себя, если очень стараетесь понять что-то в разработке и не получается. Скорее всего, часть ответственности на учителе. Если речь о вашем разработчике — просите объяснить яснее, вы имеете право понимать.

«Проклятие знания» в действии. https://ru.wikipedia.org/wiki/%D0%9F%D1%80%D0%BE%D0%BA%D0%BB%D1%8F%D1%82%D0%B8%D0%B5_%D0%B7%D0%BD%D0%B0%D0%BD%D0%B8%D1%8F