Forwarded from Уютный IT адочек
Обсуждаем документацию с @docops на хайлоад сибирь.
Основная боль пришедших - в мотивации людей. Как будто все хотят, но не могут.
К сожалению, инженеры и менеджеры не заинтересованы в том, чтобы делиться своими знаниями. Это сложно, и вообще - зачем делать себя заменимым? Тогда ж в любой момент тебя уволят.
Самое смешное - того человека, который делает бизнес отказоустойчивым не уволят, это слишком ценно для бизнеса.
Но новичков к этой мысли надо подводить и заставлять.
Основная боль пришедших - в мотивации людей. Как будто все хотят, но не могут.
К сожалению, инженеры и менеджеры не заинтересованы в том, чтобы делиться своими знаниями. Это сложно, и вообще - зачем делать себя заменимым? Тогда ж в любой момент тебя уволят.
Самое смешное - того человека, который делает бизнес отказоустойчивым не уволят, это слишком ценно для бизнеса.
Но новичков к этой мысли надо подводить и заставлять.
Пост благодарностей
За последний месяц мы, Сибирское сообщество техписателей, побывали сразу на двух крупных конференциях: РИТ++ и HighLoad++ Siberia.
На обеих конференциях мы провели митапы о документации и управлении знаниями, пообщались со множеством инженеров и технических менеджеров. А ещё наладили сотрудничество с организаторами других IT-сообществ по всей России.
Как мы туда попали? Нас пригласил Олег Бунин, организатор этих двух и ещё множества отличных конференций. Взял и подарил билеты нам и другим активистам сообществ. А на HighLoad ещё и выделил нам стенд в экспертной зоне. Спасибо Олегу и всему оргкомитету за помощь и сотрудничество!
Кстати, в Москву на РИТ++ я ездил в рабочее время и в командировку, как сотрудник компании Plesk. Ещё Plesk сильно помогает нам с митапами в Новосибирске. Спасибо за поддержку!
Наконец, я благодарю всех, с кем мы пообщались за дни конференций. Вы рассказали нам о множестве проблем и поделились интересными решениями. Вы очень крутые специалисты, с вами интересно и ценно общаться.
На фото Олег Бунин и Юлия Поповкина зашли на наш стенд в экспертной зоне.
За последний месяц мы, Сибирское сообщество техписателей, побывали сразу на двух крупных конференциях: РИТ++ и HighLoad++ Siberia.
На обеих конференциях мы провели митапы о документации и управлении знаниями, пообщались со множеством инженеров и технических менеджеров. А ещё наладили сотрудничество с организаторами других IT-сообществ по всей России.
Как мы туда попали? Нас пригласил Олег Бунин, организатор этих двух и ещё множества отличных конференций. Взял и подарил билеты нам и другим активистам сообществ. А на HighLoad ещё и выделил нам стенд в экспертной зоне. Спасибо Олегу и всему оргкомитету за помощь и сотрудничество!
Кстати, в Москву на РИТ++ я ездил в рабочее время и в командировку, как сотрудник компании Plesk. Ещё Plesk сильно помогает нам с митапами в Новосибирске. Спасибо за поддержку!
Наконец, я благодарю всех, с кем мы пообщались за дни конференций. Вы рассказали нам о множестве проблем и поделились интересными решениями. Вы очень крутые специалисты, с вами интересно и ценно общаться.
На фото Олег Бунин и Юлия Поповкина зашли на наш стенд в экспертной зоне.
Ошибки утекают в интерфейс
Бабушка пришла на остановку и ждёт автобус. Раньше она просто ждала и не знала, когда он придёт. Но теперь есть электронное табло, благодаря которому бабушка не знает ещё и что такое сервер, и почему он недоступен.
Это утечка: ошибка из мира кода попала в мир пользователя. Не надо так. Оборачивайте ошибки в понятную форму. Если нечего сказать пользователю — можно было бы вообще ничего не показывать.
В идеале сообщение об ошибке должно помогать пользователю решить его проблему. Об этом в следующем посте.
Бабушка пришла на остановку и ждёт автобус. Раньше она просто ждала и не знала, когда он придёт. Но теперь есть электронное табло, благодаря которому бабушка не знает ещё и что такое сервер, и почему он недоступен.
Это утечка: ошибка из мира кода попала в мир пользователя. Не надо так. Оборачивайте ошибки в понятную форму. Если нечего сказать пользователю — можно было бы вообще ничего не показывать.
В идеале сообщение об ошибке должно помогать пользователю решить его проблему. Об этом в следующем посте.
Про docops-подход к локализации пишет Дмитрий Симонов, CTO компании Дримсим.
Кроме перечисленных им платформ для локализации знаю ещё transifex.com и pootle.translatehouse.org
Если у вас есть опыт использования таких инструментов — поделитесь в @docsascode
Кроме перечисленных им платформ для локализации знаю ещё transifex.com и pootle.translatehouse.org
Если у вас есть опыт использования таких инструментов — поделитесь в @docsascode
Forwarded from Заметки на техдирском via @like
Про локализацию софта
https://www.youtube.com/watch?v=mIwkvkwq96o
К моему удивлению новое обильное многочисленное поколение разработчиков, сталкиваясь с задачами по локализации используют в основном методы костыльно-ориентированного программирования. Так как эти задачи сами по себе и без выбора инструментария весьма непросты и требуют аккуратности, такие костыльные решения ещё больше вгоняют проекты в сложное для поддержки решение.
Самым первым систематичным и удобным подходом к решению задачи стал GNU GetText: https://ru.wikipedia.org/wiki/Gettext, хранение переводов в .po файлах или их модификациях.
За ним подтянулись аналогичные решения на практически всех платформах. Это или нативные решения на уровне стандартных классов, как сделано в Android и iOs или дополнительные библиотеки, как в многочисленных скриптовых и не только языках:
* Android - https://developer.android.com/guide/topics/resources/localization
* iOs -https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html
* php/Symphony - https://symfony.com/doc/current/components/translation.html, включающий в себе массу провайдеров поставщиков переводов, в том числе и https://api.symfony.com/4.0/Symfony/Component/Translation/Loader/MoFileLoader.html
После внедрения этого решения разработчики получают в едином месте все необходимые лексемы для переводов. Но с этого встаёт задача о поддержке этих переводов в актуальном состоянии переводчиками и менеджерами.
Задача эта настолько непроста и зависит от множества людей и факторов, что, например, телеграмму пришлось даже запустить собственную платформу для переводов: https://translations.telegram.org/
Если же свою платформу разрабатывать не хочется, есть готовые решения:
* https://crowdin.com/
* https://gitlocalize.com/
* https://poeditor.com/
* https://localise.biz/
Они умеют экспортировать/импортировать в любые форматы, в т.ч. те, которые используются в профессиональных программах для переводчиков, и не всегда это .po
Так, например, для андроида вместо .po файлов используется аналог strings.xml, а для ios - Localizable.strings
Немаловажным качеством этих платформ являются удобные интерфейсы и разделении прав для переводчиков и менеджеров, позволяющие им заниматься своей работой, а не программированием.
Итого, true way для локализации является использование gettext или аналогов в стыковке с платформой по менеджменту переводов, умеющей экспортировать переводы в нужные форматы.
https://www.youtube.com/watch?v=mIwkvkwq96o
К моему удивлению новое обильное многочисленное поколение разработчиков, сталкиваясь с задачами по локализации используют в основном методы костыльно-ориентированного программирования. Так как эти задачи сами по себе и без выбора инструментария весьма непросты и требуют аккуратности, такие костыльные решения ещё больше вгоняют проекты в сложное для поддержки решение.
Самым первым систематичным и удобным подходом к решению задачи стал GNU GetText: https://ru.wikipedia.org/wiki/Gettext, хранение переводов в .po файлах или их модификациях.
За ним подтянулись аналогичные решения на практически всех платформах. Это или нативные решения на уровне стандартных классов, как сделано в Android и iOs или дополнительные библиотеки, как в многочисленных скриптовых и не только языках:
* Android - https://developer.android.com/guide/topics/resources/localization
* iOs -https://developer.apple.com/library/content/documentation/MacOSX/Conceptual/BPInternational/LocalizingYourApp/LocalizingYourApp.html
* php/Symphony - https://symfony.com/doc/current/components/translation.html, включающий в себе массу провайдеров поставщиков переводов, в том числе и https://api.symfony.com/4.0/Symfony/Component/Translation/Loader/MoFileLoader.html
После внедрения этого решения разработчики получают в едином месте все необходимые лексемы для переводов. Но с этого встаёт задача о поддержке этих переводов в актуальном состоянии переводчиками и менеджерами.
Задача эта настолько непроста и зависит от множества людей и факторов, что, например, телеграмму пришлось даже запустить собственную платформу для переводов: https://translations.telegram.org/
Если же свою платформу разрабатывать не хочется, есть готовые решения:
* https://crowdin.com/
* https://gitlocalize.com/
* https://poeditor.com/
* https://localise.biz/
Они умеют экспортировать/импортировать в любые форматы, в т.ч. те, которые используются в профессиональных программах для переводчиков, и не всегда это .po
Так, например, для андроида вместо .po файлов используется аналог strings.xml, а для ios - Localizable.strings
Немаловажным качеством этих платформ являются удобные интерфейсы и разделении прав для переводчиков и менеджеров, позволяющие им заниматься своей работой, а не программированием.
Итого, true way для локализации является использование gettext или аналогов в стыковке с платформой по менеджменту переводов, умеющей экспортировать переводы в нужные форматы.
Польза и ценность технического писателя
«Я теперь хочу нанять себе техписателя, потому что знаю, что есть нормальные техписатели» — сказал мне на Highload Siberia Александр Титов, управляющий партнёр компании Экспресс 42.
Надеюсь, Александр ещё расскажет, какими он видит нормальных техписателей. Я вижу их так: «разговаривают на языке инженеров и бизнеса, понимают их глобальные задачи и хотят решать эти задачи».
Хочу больше писать о том, как технический писатель может приносить пользу в масштабе компании. Хочу сокращать разрыв между писателями, инженерами и бизнесом. Пожалуйста, поделитесь своими мыслями о пользе техписателя в чате @docsascode или напишите мне (@Nick_Volynkin). Этим вы очень поможете мне и моим коллегам. А мы постараемся быть полезными всей IT-отрасли.
На фото Александр зашёл к нам на стенд на Highload Siberia.
«Я теперь хочу нанять себе техписателя, потому что знаю, что есть нормальные техписатели» — сказал мне на Highload Siberia Александр Титов, управляющий партнёр компании Экспресс 42.
Надеюсь, Александр ещё расскажет, какими он видит нормальных техписателей. Я вижу их так: «разговаривают на языке инженеров и бизнеса, понимают их глобальные задачи и хотят решать эти задачи».
Хочу больше писать о том, как технический писатель может приносить пользу в масштабе компании. Хочу сокращать разрыв между писателями, инженерами и бизнесом. Пожалуйста, поделитесь своими мыслями о пользе техписателя в чате @docsascode или напишите мне (@Nick_Volynkin). Этим вы очень поможете мне и моим коллегам. А мы постараемся быть полезными всей IT-отрасли.
На фото Александр зашёл к нам на стенд на Highload Siberia.
Конспекты про документацию и управление знаниями
Собрал в один список все конспекты с двух конференций. Старые посты со ссылками удалил.
— Документация: у кого что болит: митап на РИТ++,
— и ещё один на Highload++ Siberia.
— Польза от управления знаниями в компании.
— Управление знаниями в инженерных командах.
Собрал в один список все конспекты с двух конференций. Старые посты со ссылками удалил.
— Документация: у кого что болит: митап на РИТ++,
— и ещё один на Highload++ Siberia.
— Польза от управления знаниями в компании.
— Управление знаниями в инженерных командах.
Документ готов, когда его начали дополнять
Продолжаю делиться идеями, добытыми на двух конференциях. Игорь Цупко, директор по R&D в компании Флант, так определяет definition of done для внутренней документации:
Написать и внедрить документ — значит добиться, чтобы ваши коллеги начали его дополнять. Это означает, что они настолько уверены в ценности документа, что охотно тратят на него время.
Если не дополняют — ищите причину:
— Документ не внедрён. Тогда нужно буквально пойти и внедрить. Поговорить с людьми, рассказать, продать. Это может занять гораздо больше времени, чем вам казалось, но пока документ не внедрён, выпускать его новую версию может быть бессмысленно.
— Люди не умеют/боятся пользоваться инструментами для дополнения документа. Да, так тоже бывает на ранних стадиях жизни. Каждого нужно провести за ручку или обеспечить механику, чтобы кто-то его проводил за ручку.
— Люди боятся вообще писать. Тогда нужно дать им в помощь писателя, чтобы тот оформлял их мысли.
— Документ бесполезен. Нужно вернуться к целеполаганию и понять, в чём задача. А потом наполнить документ пользой. Про целеполагание в документах я обязательно ещё расскажу.
— Документ никому не адресован. Для работы с этим аспектом есть отличный инструмент — граф коммуникаций. Это ещё одно сокровище, добытое на конференции и о нём тоже будет отдельный пост.
---
Игорь пишет заметки о руководстве командой и управлении знаниями в @lovely_it_hell.
Вот он что-то эмоционально рассказывает на митапе про управление знаниями в инженерных командах:
Продолжаю делиться идеями, добытыми на двух конференциях. Игорь Цупко, директор по R&D в компании Флант, так определяет definition of done для внутренней документации:
Написать и внедрить документ — значит добиться, чтобы ваши коллеги начали его дополнять. Это означает, что они настолько уверены в ценности документа, что охотно тратят на него время.
Если не дополняют — ищите причину:
— Документ не внедрён. Тогда нужно буквально пойти и внедрить. Поговорить с людьми, рассказать, продать. Это может занять гораздо больше времени, чем вам казалось, но пока документ не внедрён, выпускать его новую версию может быть бессмысленно.
— Люди не умеют/боятся пользоваться инструментами для дополнения документа. Да, так тоже бывает на ранних стадиях жизни. Каждого нужно провести за ручку или обеспечить механику, чтобы кто-то его проводил за ручку.
— Люди боятся вообще писать. Тогда нужно дать им в помощь писателя, чтобы тот оформлял их мысли.
— Документ бесполезен. Нужно вернуться к целеполаганию и понять, в чём задача. А потом наполнить документ пользой. Про целеполагание в документах я обязательно ещё расскажу.
— Документ никому не адресован. Для работы с этим аспектом есть отличный инструмент — граф коммуникаций. Это ещё одно сокровище, добытое на конференции и о нём тоже будет отдельный пост.
---
Игорь пишет заметки о руководстве командой и управлении знаниями в @lovely_it_hell.
Вот он что-то эмоционально рассказывает на митапе про управление знаниями в инженерных командах:
Обзорная статья про диаграммы-как-код
На Хабре сегодня опубликовали статью про PlantUML. Это текстовый формат для описания диаграмм и программа, которая делает картинку из текстового описания.
В комментариях, как это часто бывает, обсуждают позицию «документация не нужна, потому что есть код».
Рекомендую прочитать статью и приглашаю принять участие в обсуждении: PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации.
На Хабре сегодня опубликовали статью про PlantUML. Это текстовый формат для описания диаграмм и программа, которая делает картинку из текстового описания.
В комментариях, как это часто бывает, обсуждают позицию «документация не нужна, потому что есть код».
Рекомендую прочитать статью и приглашаю принять участие в обсуждении: PlantUML — все, что нужно бизнес-аналитику для создания диаграмм в программной документации.
Как замапить код и его изменения на требования бизнеса
Вопрос, который мы обсуждали с разными людьми на РИТ, Highload Siberia, в чате TeamLeadConf и на кухне в компании Plesk. И продолжаем обсуждать с Дмитрием Симоновым (@r2d2_e2e4, канал @ctorecords).
Задача нетривиальная, требует как правильных инструментов, так и культуры/привычек их использования.
Приглашаю вас поделиться идеями и опытом в чате @ctorecordschat.
Вопрос, который мы обсуждали с разными людьми на РИТ, Highload Siberia, в чате TeamLeadConf и на кухне в компании Plesk. И продолжаем обсуждать с Дмитрием Симоновым (@r2d2_e2e4, канал @ctorecords).
Задача нетривиальная, требует как правильных инструментов, так и культуры/привычек их использования.
Приглашаю вас поделиться идеями и опытом в чате @ctorecordschat.
Forwarded from Заметки на техдирском via @like
Волынкин Николай @Nick_Volynkin поднимает в своём канале @docops одну из фундаментальных проблем в современной разработки, актуальную для компаний любого размера, начиная от стартапов и заканчивая многослойными большими корпорациями: как замапить код и его изменения на требования бизнеса.
Например, мы хотим поменять какой-то участок кода. Как найти все требования, которые он реализует? Как спрогнозировать последствия от изменения?
Кажется, что для этого нужно заранее выстраивать цепочку от коммитов к задачи в трекере и к общим документам уровня feature vision или контракта. Просто номера задачи в сообщении коммита не хватает — часто в задаче есть описание только на функциональном уровне, но не рассказано про значение для бизнеса.
Например, мы хотим поменять какой-то участок кода. Как найти все требования, которые он реализует? Как спрогнозировать последствия от изменения?
Кажется, что для этого нужно заранее выстраивать цепочку от коммитов к задачи в трекере и к общим документам уровня feature vision или контракта. Просто номера задачи в сообщении коммита не хватает — часто в задаче есть описание только на функциональном уровне, но не рассказано про значение для бизнеса.
Документация как комиксы
Когда мне было четыре или пять лет, мама подарила мне книжку комиксов «Откуда берутся дети». Я прочитал, всё понял и в следующие лет 7-10 знал точно больше своих сверстников. Конечно, потом были и другие источники, но тот комикс дал мне начальные знания и избавил от кучи недоразумений.
Теперь мне уже гораздо больше годиков, но за последний месяц я с удовольствием прочитал целых три комикса:
— «Приятного плавания с Kubernetes».
Древнегреческий мореплаватель Ясон теперь работает в IT и руководит отрядом боевых админов. Это сложнее, чем засевать поля драконьими зубами. Богиня Гера знакомит его с «κυβερνήτης», «рулевым». Конечно, Рулевой решает сразу все проблемы Ясона — это же сказка, а в сказке так бывает.
— Как работает DNS.
DNS-запрос путешествует в поисках IP-адреса.
— Как работает HTTPS.
Сертификот и другие звери рассказывают о том, как защитить сообщения в интернете от злонамеренных крабов.
---
Кстати, от того же корня, что и «кубернетес», образованы слова «губернатор» и «гувернёр».
Знаете другие примеры хорошей документации в картинках? Приходите обсудить их в @docsascode.
Когда мне было четыре или пять лет, мама подарила мне книжку комиксов «Откуда берутся дети». Я прочитал, всё понял и в следующие лет 7-10 знал точно больше своих сверстников. Конечно, потом были и другие источники, но тот комикс дал мне начальные знания и избавил от кучи недоразумений.
Теперь мне уже гораздо больше годиков, но за последний месяц я с удовольствием прочитал целых три комикса:
— «Приятного плавания с Kubernetes».
Древнегреческий мореплаватель Ясон теперь работает в IT и руководит отрядом боевых админов. Это сложнее, чем засевать поля драконьими зубами. Богиня Гера знакомит его с «κυβερνήτης», «рулевым». Конечно, Рулевой решает сразу все проблемы Ясона — это же сказка, а в сказке так бывает.
— Как работает DNS.
DNS-запрос путешествует в поисках IP-адреса.
— Как работает HTTPS.
Сертификот и другие звери рассказывают о том, как защитить сообщения в интернете от злонамеренных крабов.
---
Кстати, от того же корня, что и «кубернетес», образованы слова «губернатор» и «гувернёр».
Знаете другие примеры хорошей документации в картинках? Приходите обсудить их в @docsascode.
Целеполагание технического документа
Авторы всех трёх комиксов из прошлого поста проделали отличную работу с целеполаганием:
— Комиксы написаны для конкретной аудитории. Ясон — воплощение целевого читателя. Он руководит админами в крупной компании, уже успел поработать с контейнерами и погибает под ворохом типичных проблем. Гера, воплощение автора, упоминает всё, что он уже должен знать, и подробно объясняет всё новое.
— Решают задачу читателя — понять основы сложной предметной области. После этого читатель сможет изучать её дальше или использует знания, чтобы принять решение. Все комиксы объясняют сложную тему, при этом развлекают и помогают удержать внимание. Думаю, начинать знакомство с
— Решают задачу бизнеса. В первом комиксе Гера попутно продаёт читателю Google Cloud. Второй и третий приглашают на сайт компании DNSimple, которая предоставляет DNS и перепродаёт SSL-сертификаты.
Эти критерии целеполагания я когда-то узнал от Семёна Факторовича на курсе Advanced technical writing и с тех пор использую их для всех технических документов. Жанр документа может быть любой: комментарии в коде, пользовательская документация, статья на Хабре или пост в канале, который вы сейчас читаете.
Авторы всех трёх комиксов из прошлого поста проделали отличную работу с целеполаганием:
— Комиксы написаны для конкретной аудитории. Ясон — воплощение целевого читателя. Он руководит админами в крупной компании, уже успел поработать с контейнерами и погибает под ворохом типичных проблем. Гера, воплощение автора, упоминает всё, что он уже должен знать, и подробно объясняет всё новое.
— Решают задачу читателя — понять основы сложной предметной области. После этого читатель сможет изучать её дальше или использует знания, чтобы принять решение. Все комиксы объясняют сложную тему, при этом развлекают и помогают удержать внимание. Думаю, начинать знакомство с
man kubectl мне было бы гораздо тяжелее. Конечно, комикс не заменит документацию, но она решает совсем другие задачи.— Решают задачу бизнеса. В первом комиксе Гера попутно продаёт читателю Google Cloud. Второй и третий приглашают на сайт компании DNSimple, которая предоставляет DNS и перепродаёт SSL-сертификаты.
Эти критерии целеполагания я когда-то узнал от Семёна Факторовича на курсе Advanced technical writing и с тех пор использую их для всех технических документов. Жанр документа может быть любой: комментарии в коде, пользовательская документация, статья на Хабре или пост в канале, который вы сейчас читаете.
Какие критерии вы используете, когда ставите или принимаете задачу на технический документ?
public poll
Знаю и использую эти критерии – 9
👍👍👍👍👍👍👍 60%
@Elaneor, @solntseN, @SoNiQQQue, @Nick_Volynkin, @Lananovikova, @kipkaev, @annacraneo, Алена, Sagi
Теперь знаю и буду использовать – 5
👍👍👍👍 33%
@Andreichernov, @Altenrion, @IharReznichenka, @Lytkini, @dr_heart
Использую другие критерии, расскажу в @docsascode – 1
👍 7%
@mnmlsniper
Не буду использовать (интересно, почему → @docsascode)
▫️ 0%
👥 15 people voted so far.
public poll
Знаю и использую эти критерии – 9
👍👍👍👍👍👍👍 60%
@Elaneor, @solntseN, @SoNiQQQue, @Nick_Volynkin, @Lananovikova, @kipkaev, @annacraneo, Алена, Sagi
Теперь знаю и буду использовать – 5
👍👍👍👍 33%
@Andreichernov, @Altenrion, @IharReznichenka, @Lytkini, @dr_heart
Использую другие критерии, расскажу в @docsascode – 1
👍 7%
@mnmlsniper
Не буду использовать (интересно, почему → @docsascode)
▫️ 0%
👥 15 people voted so far.
Forwarded from Канал Ильи Бирмана
Сайт перечисляет причины, по которым деньги пользователя до него не дошли. Из-за использования списка с точками кажется, что случились все эти беды. Если заменить список на вариант со скобками 1) 2) 3) 4) 5), будет читаться чуть легче. Никто не знает, почему так, но список с точками скорее воспринимается как элементы, соединённые союзом «и», а со скобками — союзом «или».