Пишет Игорь Цупко, мой единомышленник и соратник по KnowledgeConf:

Привет, коллеги!

Последний год мы с коллегами из KnowledgeConf занимаемся систематизацией и исследованиями подходов к менеджменту знаний и оформляем это всё в виде Прагматичного Гайда.

Мы выработали ряд походов и понимание того, как запустить или сделать более эффективным онбординг, выстроить документирование, обмен знаниями, сформулировать и распространить лучшие технологические практики внутри команды и компании. И мы хотим поделиться этим знанием с вами.

Если вы сейчас ищете подходы улучшить процессы управления знаниями — давайте пообщаемся и обменяемся опытом. Редакции гайда будет полезно узнать об актуальных для разработчиков проблемах, а вы, возможно, пополните свою копилку хорошими практическими идеями.

Чтобы принять участие — забейте временной слот (30-40 минут) через Calendly. По возможности укажите при забивании слота — какие проблемы менеджмента знаний для вас актуальны, чтобы нам не терять времени.

Я сам записался, между прочим. И вам рекомендую.

Добавил чат любителей AsciiDoctor — @asciidoctor.

AsciiDoctor — это ещё один легковесный язык разметки и генератор документации для него. Язык разметки похож на reStructuredText: выразительный, семантический но сложнее и менее популярный, чем Markdown.
https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/

У меня тут заканчивается второй день отпуска, и я постепенно начинаю понимать, что отпуск стоило взять 1) гораздо раньше и 2) на гораздо больший срок, может быть, на месяц.

Берегите себя, друзья. :)

Вторая мысль в отпуске: я работаю на одной работе 4 года и уже довольно неточно знаю, сколько я на самом деле стою. Пора это проверить. ;)

Если вам нужен человек, который будет внедрять DocOps и писать доки для разработчиков — напишите мне в личку (@nick_volynkin), пожалуйста.

Гильдии в Plesk, Xsolla, Miro, РТ МИС и Сбере.

Ребята из разных компаний делятся опытом внутренних гильдий, то есть профессиональных сообществ. Только что сам начал смотреть, ничего не напишу в анонсе. Но гильдии — это отличная тема. У нас их аж несколько: QA, devops, frontend, backend, security, accessibility.

Судя по набору компаний, будет чертовски интересно. Рекомендую.

https://youtu.be/rCgXq1i4D9E

Максим Лапшин (Flussonic.com) написал подробный обзор @foliantdocs — комбайна для сборки и публикации документации в веб, PDF, конфлюенс и разные другие форматы. Доки Flussonic теперь собираются именно Фолиантом.

С разрешения автора публикую обзор здесь:

Я перетащил нашу документацию с самописной обертки вокруг ruby markdown на foliant.

Почему вообще возник вопрос о перезде?

* код писал я, причем очень давно и никакого желания дальше его развивать не было
* то, как я генерировал PDF с помощью ruby prawn было мягко говоря по-спартански

По сравнению с mkdocs и прочими фолиант подкупил интеграцией с пандоком, очень важная штука: бесплатно из коробки top-level поддержка PDF.

Чего мне не хватало из коробки в фолианте?

1. переименовывания результирующих файлов из их понятных имен вида live/publish.md в ужасный SEO-транслит potokovaya-peredacha/publikaciya
2. редиректов с человеческих unix-имен на транслит
3. возможности понять, какой урл будет у этой же страницы на другом языке для иконки языка
4. выгрузка кусков конфига из английской документации на диск для автотестов (мы тестируем документацию) и вставка их в русский вариант
5. выгрузка кусков документации в json для вставки их в админку нашего продукта


В целом всё это получилось решить плагинами, один из которых к mkdocs.

С чем возникли проблемы:

1. рубийный маркдаун существенно вольготнее относится к верске, чем питонячий. Пришлось много текста править
2. после рубийной Nokogiri, парсить HTML регекспами в питоне очень грустно. Очень не хватает API по объектному доступу к AST markdown
3. есть некоторая путаница между слоями метаданных фолианта и mkdocs. Вообще хотелось бы чтобы это не было разными вещами
4. процессоры фолианта разрешают падать и идти дальше. Реалии авторов фолианта такие, что им важнее собрать хоть что-то, чем собрать всё корректно. Мне наоборот — ворнинг уже повод упасть и не собирать документацию.
5. Пришлось написать немало кода, который подправлял плохую верстку в наших 3 миллионах символов (280 тыс слов)


Чего отдельно понравилось:

1. глобальное пространство имен анкоров. Ссылаться на уникальное по проекту имя секции — бесценно.
2. упаковка картинок и прочих ассетов в webpack-стиле, это важно
3. ну и вообще то, что люди решили его опенсорснуть и довести до отчуждаемого состояния. Это круто.

Таня Фокина, UX-писатель из ЦФТ, рассказывает о своей профессии и решает задачки в канале @rishavant.

С Таней мы давно знакомы, вместе работали в переводческой артели «Надмозг» и в ПК конференции DocFactor. Таня шарит, так что канал я очень рекомендую.

Мне особенно понравился пост про то, как полезно выяснять задачу бизнеса. У писателя по-хорошему не должно быть задачи «написать текст», как и у плотника нет задачи  «поиспользовать молоток», а у хирурга «порезать скальпелем». Это всё инструменты, а не задачи.

https://t.me/rishavant/7

Мы тут поспорили, что канал @rishavant наберёт сотню за сутки. Осталось полчаса и 4 человека ;)

Писал это знакомой, которая хочет перейти в технические писатели. Но это верно для всех, кто в свои ХХ лет хочет поменять профессию и сомневается, что это можно сделать, не имея опыта.

Я в вас верю, вы сможете.

Смотри. У тебя на самом деле не ноль лет опыта, потому что важен и полезен много какой опыт.

Есть общие навыки работы с информацией. Понимать незнакомое, структурировать, выделять связи, объяснять, излагать текстом.

Есть софт-скиллы. Учиться. Принимать обратную связь, в том числе негативную. Давать обратную связь, тоже в том числе негативную. Организовывать свой труд. Расставлять приоритеты. Писать понятные письма. Задавать вопросы — понятые, полные, открытые вопросы, это очень редко кто умеет. Рефлексировать. Отдыхать. Печатать десятью пальцами и вслепую. Договариваться с людьми, передоговариваться. Давать обещания, держать обещания, требовать по обещаниям тебе. Благодарить и принимать благодарность. Ошибаться и идти дальше, извлекать опыт из ошибок, своих и чужих. Давать задачи, брать задачи, руководить и быть руководимой. Сообщать заранее, когда не успеваешь сделать задачу в срок. Обращаться за помощью. Понимать других людей, их эмоции, цели, доступные им знания.

Всё это ты уже насколько-то умеешь. Это твой опыт. Он не нулевой. И всё это настолько же важно в работе, как и знание предметной области и специфических писательских инструментов. Даже больше: предметной области тебя любая компания легко научит. А вот софт-скиллам учить сложно и больно. У тебя они уже развиты и это твоя сильная сторона.

Екатерина Носкова из Xsolla рассказала про аналитику в документации. И не просто о сырых данных вроде количества просмотров, а о метриках, привязанных к реальной пользе для бизнеса. Это очень круто, читаю и восхищаюсь.

Xsolla — это платёжная система для игр и других приложений. Вот какие бизнес-метрики есть в доке Xsolla:

— Доля интеграций (внедрений платёжных инструментов Xsolla), которые клиенты сделали своими силами, не напрягая техподдержку.
— Изменение затрат на техническую поддержку, когда пользователь или сотрудник поддержки находят готовое решение в доке.

И внутренние метрики, показатели здоровья доки:
— Посещаемость по типу аудитории (b2b, b2c), языку и продукту. Просто суммарная посещаемость не имеет смысла, важны разрезы.
— Средняя скорость загрузки страниц. Это влияет сразу на UX и SEO.
— Индекс удовлетворённости пользователей — считается через форму фидбека 👍/👎.
— Качество документации, измеренное по нескольким показателям.
— Юзабилити документации — по анализу тепловых карт и записей сессий.

Читайте статью целиком, там много полезных идей. https://medium.com/xsolla-tech/analytics-in-documentation-d814bbbe6ea6

Подборка хороших сайтов с документацией, чтобы черпать вдохновение и красть, как художник: https://devportalawards.org/

С новым годом, друзья! :)

Писателям тоже будет полезно.

https://www.transposit.com/blog/2020.01.30-writing-runbook-documentation-when-youre-an-sre

Вообще, смешно и грустно, что к половине статей про документацию берут иллюстрацию с клавиатурой, печатной машинкой, пером и чернильницей или чем-то подобным. Как будто основная работа технического писателя в том, чтобы писать. Вот нифига, основная работа — думать и исследовать. Как и у разработчика и у кучи других профессий. Когда хорошо подумаешь, писать несложно.

Таня @rishavant запустила анонимный опрос о зарплатах UX-писателей. Если вы пишете интерфейсные тексты — пожалуйста, ответьте на пару вопросов. Результаты Таня потом опубликует.

https://forms.gle/gJD8Q9zVzmUP3Zbd9

Всем ГОСТописателям рекомендую слушать выпуск «Нового подкаста» про AsciiDoc и его использование в компании КУРС. Переходите уже к нам на светлую сторону, у нас docs-as-code и печеньки.

Ссылки на все платформы: https://newpodcast2.live/podcast/vanya-and-asiidoc/

Известный редактор, автор книги про текст в интерфейсе, возмущённо пишет о людях, которые путают "надеть" и "одеть", когда просят его надеть медицинскую маску. Говорят "езжайте" вместо "поезжайте" [в лифте без меня, потому что вы без маски и можете меня заразить].

А как же уважение и забота о людях? Без этого зачем вообще нужна редактура, все эти тексты?

Люди ведь важнее, чем слова.