DocOps

Тут идёт голосование для вручения премии Highload++ 2019. Предполагается, что премией должны быть награждены люди, которые оказали значительное позитивное влияние на отрасль в целом, продвинули её вперёд к добру, свету и позитиву. Голосование вот тут: http://www.highload.ru/moscow/2019/award (красная кнопка "Проголосовать" справа) И не то, чтобы я призывал голосовать за какого-то кандидата, но именно это я сейчас и попробую сделать 🙂 Мне кажется, человек, который очень достоин премии, но может быть позабыт - это Филлип Кулин, автор https://usher2.club/ и неугомонный борец с безумием в органах власти. Роскомнадзор и попытки управлять интернетом никуда не денутся, некомпетентность управленцев - останется, и мне кажется, что без работы таких людей как Фил (а он не только делает сервисы, публично вскрывает абсурд и косяки в работе гос. органов, но и пытается общаться с госами на их языке, чтобы ну хоть как-то повлиять на ситуацию), в нашей действительности - никак. Фил достоин, голосуйте, пожалуйста, за Фила.

Технические писатели и UX-писатели. Автор «Плавучей редакции» Владимир пишет о профессиях технического и UX-писателя: https://t.me/editboat/236. Я считаю, что технические писатели владели инфостилем и занимались UX-writing'ом ещё до того, как появились оба этих слова. У нас есть выверенные процессы и стайлгайды, которые охватывают всё от запятых до business value. А ещё мы бережно относимся и умеем работать с терминами — в технических текстах и интерфейсах они очень важны. Интерфейсы, с которыми мы работаем — это не только кнопки на сайтах, мы умеем писать тексты для CLI и API. Встроенная документация в нативных библиотеках, всякие javadoc и docstring — это тоже интерфейсные тексты. Не все техписатели этим занимаются, но таких много. Ещё там есть опрос об отношении между двумя профессиями. Для меня UX-писатель — это скорее специализация техписателя. Думаю, что заниматься только текстами или только документацией к сложному продукту — дело неэффективное. Но есть и другие продукты, где пользователь читает только текст в интерфейсе и задача писателя — донести нужные знания только через этот текст. Наверное, в них можно стать UX-писателем из дизайнера, копирайтера или аналитика.

Plesk changelogs. Переделал страницу с журналом изменений Plesk. Весь вечер сижу и радуюсь результату. (Как мало надо трудоголику). Под капотом там — автомиграция контента, написанного за четыре года, — мощь и тупость Jekyll, — немного методологии БЭМ, — совсем немного Jenkins pipelines, и — changelog API на горизонте. Хотите почитать статью с подробностями? Если вам есть что сказать про вёрстку, информативность и полезность этой страницы — приходите с фидбеком. Можно в чат @docsascode, можно в личку @nick_volynkin.

Подтверждаю, слова мои. @evilmartians хорошо пишут, иногда даже про документацию :) https://twitter.com/andrey_sitnik/status/1181555123807494144

code == text На недавней конференции RubyRussia Андрей "Прогапандист" Баранов из Злых Марсиан проводил параллели между кодом и текстом: — пирамида тестирования (см. https://t.me/docops/157) — стайлгайды — «читай больше X чтобы лучше писать X» — принцип SOLID Это был lightning talk, записи нет, есть только слайды: https://speakerdeck.com/progapandist/code-equals-equals-text Что ещё есть общего? Какие практики можно переносить из кода в текст и обратно? Расскажите в @docsascode.

R Markdown настолько хорош, что попал под блокировку :) https://t.me/zatelecom/11815

​​R Markdown: The Definitive Guide Всего неделю назад вышла новая книга про R Markdown. Казалось бы, зачем миру ещё одна реализация Markdown? Во-первых, в R Markdown всё очень хорошо с выходными форматами: HTML, PDF, DOCX, четыре разных формата слайдов. Приятно иметь это всё сразу и не собирать цепочку из нескольких инструментов. Во-вторых, есть выполняемые блоки кода, которые рисуют диаграммы и любой другой контент в документе. Код можно писать на R, Python, Julia, C++, С, SQL, Fortran и других языках. Я пока не успел попробовать, но выглядит это гораздо мощнее, чем обычные языки шаблонизации вроде Jinja и Liquid. Конечно, можно к любому SSG написать своё расширение, которое будет делать что угодно при сборке документа, но тут-то не нужны расширения. Я думаю, это очень крутая фича. Она открывает путь к автодокументированию в принципе любых данных, которые вы можете собрать программно. В-третьих, в R Markdown есть режим R Notebook — когда блоки кода на R выполняются интерактивно. Вроде бы можно переиспользовать один документ с разными источниками данных. Если вы знакомы с Jupyter Notebook — это примерно оно же, только на R. А ещё в комплекте с R Markdown есть сервис Bookdown — инструмент для написания и публикации чего угодно на R Markdown. На нём уже написана куча книг по языку R. Конечно, на нём же сделана книга-документация по R Markodwn и ещё одна книга про сам сервис Bookdown. В общем, это не просто 101й парсер, а целая развитая экосистема. Стоит попробовать, особенно если ваша работа связана с обработкой данных. На скриншоте — документ R Markdown и собираемая из него интерактивная страница с визуализацией данных (источник).

​​Киберпанк

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

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

​​Налоговая служба Украины написала документацию к своему электронному кабинету на Sphinx/reST. В сайте узнаётся тема Read the Docs, можно скачать PDF и EPUB. Я считаю, для госоргана это очень круто и современно. https://cabinet.tax.gov.ua/help/intro.html Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)

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

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

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

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

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 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/.

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

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