Производите или документируете CLI-утилиту, в которой куча команд с параметрами? Подумайте про вот такой конструктор команд: http://ru.clihelper.com/. Думаю, что он будет полезен и пользователям, и вам самим:
— Поможет пользователю увидеть общую картину и сориентироваться в возможностях утилиты.
— Поможет собрать сложные команды, которые сразу будут работать правильно. Это снижает время до первого успешного использования, и этим улучшает конверсию из тех кто попробовал в тех, кто стал постоянным пользователем.
— Поможет разработчикам поддерживать консистентный синтаксис команд и понятную структуру. Они будут яснее видеть, когда структура теряет логику и порядок.
Мы в Plesk.com ещё не пробовали такое, но наверняка попробуем. О результатах расскажу.
— Поможет пользователю увидеть общую картину и сориентироваться в возможностях утилиты.
— Поможет собрать сложные команды, которые сразу будут работать правильно. Это снижает время до первого успешного использования, и этим улучшает конверсию из тех кто попробовал в тех, кто стал постоянным пользователем.
— Поможет разработчикам поддерживать консистентный синтаксис команд и понятную структуру. Они будут яснее видеть, когда структура теряет логику и порядок.
Мы в Plesk.com ещё не пробовали такое, но наверняка попробуем. О результатах расскажу.
Clihelper
cli helper. Помощники
cli helper. Any docs, documents, manual, tutorial about unix and linux command. Option reminder for unix command. cli helper.
Ещё один интересный способ облегчить жизнь пользователя и помочь ему освоить интерфейс командной строки:
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.