DocOps

Обсуждали на кухне доклад Александра Тоболя про UDP. Когда-то я конспектировал этот доклад с постоянными паузами и повторами видео. Александр рассказывает быстро, а плотность информации довольно большая, так что сходу сложно уловить весь смысл. Интересно, сколько успели понять те, кто слушал доклад вживую на конференции.

Ничего не напоминает? Это же UDP. В докладе про UDP!

У нас теперь есть свой человек в Лондоне :)
https://t.me/shut_up_and_write/120

Известный техписатель из Амазона Том Джонсон сделал крутейшие тесты на квалификацию, а потом разочаровался в них.

Follow-up to 4 Technical Writing Tests Post.
It's been a while since I've written a post that has received so many negative comments as 4 Technical Writing Tests to Screen Candidates. Although many people did like the tests and found them interesting or fun, quite a few people had more negative reactions. As a result, I'm scrapping the idea of multiple choice tests as a way to filter candidates...

Приходите в @docsascode, обсудим.

Когда-нибудь здесь будет канал с нормальными вакансиями для техписателей: @docops_jobs. С описанием задач, технологий и пользы от документации, а не задолбавших всех печенек. Но не сегодня. Как-нибудь доберусь. А пока что подписывайтесь. :)

Как зачем переводить комментарии в примерах кода? Чтобы вот такие вот угарные примеры получались!
https://t.me/tech_b0lt_Genona/1130

Привет! Хочу устроить техрайтерский чятик в Беларуси — Write The Docs Минск. Когда наберем достаточно местных, сможем собраться на митап, кофе, другие напитки.
Добро пожаловать: https://t.me/wtd_minsk

Если вы в Беларуси и вам интересна документация — присоединяйтесь :)

Опубликованы записи докладов и слайды недавней конференции API the Docs: https://pronovix.com/event/api-docs-amsterdam-2019.
Там всё про документирование кода и API.

Спасибо @aselivanava за ссылку :)

«Как замотивировать наших ребят делиться своим опытом через текст?» — недавно опубликованный совет от Людмилы Сарычевой. Хорошая тема на пересечении редактуры, деврела и управления знаниями.

Я там написал коментарий на основе своего опыта в Plesk и коллективной мудрости DevRel-сообщества. Если вам есть что добавить — присоединяйтесь.

Перевод курса по документированию API теперь есть в форме сайта: https://starkovden.github.io.

​​#latex После доклада на GolangConf решил поделиться опытом создания презентации с помощью LaTeX:
https://habr.com/ru/post/471352/
Специально для этой статьи я сделал шаблоны для двух предстоящих конференций:
https://github.com/schors/hl2019theme
https://github.com/schors/sc2019theme

Вобщем, рекомендую. Программировать презентацию оказалось занимательно.

Я протормозил с анонсом, конечно. У вас есть ещё пара часов чтобы проголосовать ^. И я тоже поддерживаю Фила Кулина. Думаю, сейчас лучшее, что можно сделать для интернета — хотя бы не дать его сломать. Фил как раз этим и занимается.

Тут идёт голосование для вручения премии 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-писателем из дизайнера, копирайтера или аналитика.

DocOps pinned «Plesk changelogs. Переделал страницу с журналом изменений Plesk. Весь вечер сижу и радуюсь результату. (Как мало надо трудоголику). Под капотом там — автомиграция контента, написанного за четыре года, — мощь и тупость Jekyll, — немного методологии БЭМ, —…»

Plesk changelogs.
Переделал страницу с журналом изменений Plesk. Весь вечер сижу и радуюсь результату. (Как мало надо трудоголику).

Под капотом там
— автомиграция контента, написанного за четыре года,
— мощь и тупость Jekyll,
— немного методологии БЭМ,
— совсем немного Jenkins pipelines, и
— changelog API на горизонте.

Хотите почитать статью с подробностями?

Если вам есть что сказать про вёрстку, информативность и полезность этой страницы — приходите с фидбеком. Можно в чат @docsascode, можно в личку @nick_volynkin.

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

Подтверждаю, слова мои. @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