Ещё один интересный способ облегчить жизнь пользователя и помочь ему освоить интерфейс командной строки:
Forwarded from Записки админа
👱🏻 Natural Language для Linux.
Чего только не делают люди. Вот вам, например, попытка создания преобразователя, который бы трансформировал обычную (английскую в данном случае) письменную речь, в bash команды для управления оперционной системой (речь о Linux, конечно же).
С технарями всё и так понятно - знаем команды, знаем где посмотреть описание, знаем и умеем всем этим пользоваться. Данный же проект, ставит перед собой задачу упростить работу пользователя с командной строкой. В идеале, ему не нужно будет запоминать команды и их синтаксис, достаточно будет просто написать, например "Найди все файлы, которые были модифицированы в последние два дня" и система выполнит соответствующую команду find с нужными параметрами.
Нужен ли он? С точки зрения админа - вряд ли, но вот с точки зрения пользователя - это как минимум выглядит интересно.
Документ на 12 страницах с описанием, ссылками и исследованием доступен здесь:
https://arxiv.org/abs/1802.08979
#linux #bash
Чего только не делают люди. Вот вам, например, попытка создания преобразователя, который бы трансформировал обычную (английскую в данном случае) письменную речь, в bash команды для управления оперционной системой (речь о Linux, конечно же).
С технарями всё и так понятно - знаем команды, знаем где посмотреть описание, знаем и умеем всем этим пользоваться. Данный же проект, ставит перед собой задачу упростить работу пользователя с командной строкой. В идеале, ему не нужно будет запоминать команды и их синтаксис, достаточно будет просто написать, например "Найди все файлы, которые были модифицированы в последние два дня" и система выполнит соответствующую команду find с нужными параметрами.
Нужен ли он? С точки зрения админа - вряд ли, но вот с точки зрения пользователя - это как минимум выглядит интересно.
Документ на 12 страницах с описанием, ссылками и исследованием доступен здесь:
https://arxiv.org/abs/1802.08979
#linux #bash
Игорь Цупко рассказывает про системный и целостный подход к внутренней документации: про инструменты, процессы и цели. Рекомендую.
Forwarded from Уютный IT адочек
Как начать внедрять фиксацию знаний в компании.
Конечно, проще всего делать с самого начала, с момента, когда команда собирается. У меня был такой опыт и, по отзывам, вполне успешный (хотя есть подводные камни, о которых расскажу позже). Как поступать с командой, в которой уже сложились подходы - также в грядущих постах :)
Как начать с самого начала?
Начнём с тезисов:
- люди не хотят, не любят и не будут документировать. Их придётся заставить и научить.
- люди не умеют в русский язык
- хороших экосистем для документации не существует, их надо будет строить. И они сейчас строятся выходцами из техписовой тусовки, но медленно. Люди пока не верят в финансовую отдачу от этой движухи.
- документация - это вещь _на стыках_ между людьми/ролями. Нет смысла делать документацию в тех местах, где стыка нет.
Подробно всю эту тему освещал тут: https://www.youtube.com/watch?v=NGiN3df_YGc
В том числе в видео вы найдёте пример структуры доки и объяснение того, какую структуру доки нужно построить именно вам.
Конечно, проще всего делать с самого начала, с момента, когда команда собирается. У меня был такой опыт и, по отзывам, вполне успешный (хотя есть подводные камни, о которых расскажу позже). Как поступать с командой, в которой уже сложились подходы - также в грядущих постах :)
Как начать с самого начала?
Начнём с тезисов:
- люди не хотят, не любят и не будут документировать. Их придётся заставить и научить.
- люди не умеют в русский язык
- хороших экосистем для документации не существует, их надо будет строить. И они сейчас строятся выходцами из техписовой тусовки, но медленно. Люди пока не верят в финансовую отдачу от этой движухи.
- документация - это вещь _на стыках_ между людьми/ролями. Нет смысла делать документацию в тех местах, где стыка нет.
Подробно всю эту тему освещал тут: https://www.youtube.com/watch?v=NGiN3df_YGc
В том числе в видео вы найдёте пример структуры доки и объяснение того, какую структуру доки нужно построить именно вам.
YouTube
Документация? Не слышал
Игорь Цупко, Notamedia
Конференция Dev Party (http://devparty.ru).
Вологда, 25.03.2017
Конференция Dev Party (http://devparty.ru).
Вологда, 25.03.2017
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 или контракта. Просто номера задачи в сообщении коммита не хватает — часто в задаче есть описание только на функциональном уровне, но не рассказано про значение для бизнеса.