Выводы

— Страницы весят очень мало. Вашим читателям это понравится, если у них медленное или нестабильное соединение.
— Сервис уважает приватность читателей и не собирает никаких данных.
— Хорошо подходит для коротких заметок и конспектов.
— Пока что не подходит для публикации кода. Будем ждать обновлений

#docops_toolkit

Про что написать в следующем посте?
public poll

Обзор отличного примера интерактивной документации (какого — секрет). – 15
👍👍👍👍👍👍👍 65%
@katerina308, @etkee, @factorized, @exebeeche, @annacraneo, @anasta_ste, @DarthVader, @OlgaRevyakina, @SvetlanaNudel, @den317, @woooooowmen, @aselivanava, @slavachernikoff, @arvikon, @space_time_freedom

Как добавлять диаграммы, в том числе UML, в документацию на Sphinx. – 4
👍👍 17%
@yeugene, @Lananovikova, @PavelAlferov, @maxlapshin

Как использовать ссылки в форматах разметки, чтобы они не сломались при переводе. – 2
👍 9%
@Dark_soul_Mike, Екатерина

Память переводов: зачем нужна и как устроена. – 2
👍 9%
@i_tsupko, @vodnicear

👥 23 people voted so far.

Резюме современного инженера: репозиторий на Гитхабе с полезными скриптами для администрирования Debian, а в заголовке — ссылка на CV.

У репозитория 124 звезды, это довольно неплохо. Мой рекорд - шесть.

В резюме автор сразу пишет по делу: что умеет, что предлагает, какие принципы исповедует. Мне нравится, это вызывает интерес и доверие.
https://github.com/szepeviktor/debian-server-tools

Производите или документируете CLI-утилиту, в которой куча команд с параметрами? Подумайте про вот такой конструктор команд: http://ru.clihelper.com/. Думаю, что он будет полезен и пользователям, и вам самим:

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

Мы в Plesk.com ещё не пробовали такое, но наверняка попробуем. О результатах расскажу.

Ещё один интересный способ облегчить жизнь пользователя и помочь ему освоить интерфейс командной строки:

👱🏻 Natural Language для Linux.

Чего только не делают люди. Вот вам, например, попытка создания преобразователя, который бы трансформировал обычную (английскую в данном случае) письменную речь, в bash команды для управления оперционной системой (речь о Linux, конечно же).

С технарями всё и так понятно - знаем команды, знаем где посмотреть описание, знаем и умеем всем этим пользоваться. Данный же проект, ставит перед собой задачу упростить работу пользователя с командной строкой. В идеале, ему не нужно будет запоминать команды и их синтаксис, достаточно будет просто написать, например "Найди все файлы, которые были модифицированы в последние два дня" и система выполнит соответствующую команду find с нужными параметрами.

Нужен ли он? С точки зрения админа - вряд ли, но вот с точки зрения пользователя - это как минимум выглядит интересно.

Документ на 12 страницах с описанием, ссылками и исследованием доступен здесь:
https://arxiv.org/abs/1802.08979

#linux #bash

Игорь Цупко рассказывает про системный и целостный подход к внутренней документации: про инструменты, процессы и цели. Рекомендую.

Как начать внедрять фиксацию знаний в компании.

Конечно, проще всего делать с самого начала, с момента, когда команда собирается. У меня был такой опыт и, по отзывам, вполне успешный (хотя есть подводные камни, о которых расскажу позже). Как поступать с командой, в которой уже сложились подходы - также в грядущих постах :)

Как начать с самого начала?
Начнём с тезисов:
- люди не хотят, не любят и не будут документировать. Их придётся заставить и научить.
- люди не умеют в русский язык
- хороших экосистем для документации не существует, их надо будет строить. И они сейчас строятся выходцами из техписовой тусовки, но медленно. Люди пока не верят в финансовую отдачу от этой движухи.
- документация - это вещь _на стыках_ между людьми/ролями. Нет смысла делать документацию в тех местах, где стыка нет.

Подробно всю эту тему освещал тут: https://www.youtube.com/watch?v=NGiN3df_YGc
В том числе в видео вы найдёте пример структуры доки и объяснение того, какую структуру доки нужно построить именно вам.

Из чата @technicalwriters

да пджите радоваться) скоро сольемся с аналитиками или тестировщиками и будет новая сфера - докопс или тестопс какой нибудь :)

Будет такая сфера, обязательно будет!

Обсуждаем документацию с @docops на хайлоад сибирь.
Основная боль пришедших - в мотивации людей. Как будто все хотят, но не могут.

К сожалению, инженеры и менеджеры не заинтересованы в том, чтобы делиться своими знаниями. Это сложно, и вообще - зачем делать себя заменимым? Тогда ж в любой момент тебя уволят.
Самое смешное - того человека, который делает бизнес отказоустойчивым не уволят, это слишком ценно для бизнеса.
Но новичков к этой мысли надо подводить и заставлять.

​​Пост благодарностей

За последний месяц мы, Сибирское сообщество техписателей, побывали сразу на двух крупных конференциях: РИТ++ и HighLoad++ Siberia.

На обеих конференциях мы провели митапы о документации и управлении знаниями, пообщались со множеством инженеров и технических менеджеров. А ещё наладили сотрудничество с организаторами других IT-сообществ по всей России.

Как мы туда попали? Нас пригласил Олег Бунин, организатор этих двух и ещё множества отличных конференций. Взял и подарил билеты нам и другим активистам сообществ. А на HighLoad ещё и выделил нам стенд в экспертной зоне. Спасибо Олегу и всему оргкомитету за помощь и сотрудничество!

Кстати, в Москву на РИТ++ я ездил в рабочее время и в командировку, как сотрудник компании Plesk. Ещё Plesk сильно помогает нам с митапами в Новосибирске. Спасибо за поддержку!

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

На фото Олег Бунин и Юлия Поповкина зашли на наш стенд в экспертной зоне.

​​​​А здесь, слева направо: автор этого канала, Римма Джаникян из оргкомитета конференции, Семён Факторович и Татьяна Фокина.

​​(фото терялось, пришлось опубликовать заново)

Сменил название на более компактное.

​​Ошибки утекают в интерфейс

Бабушка пришла на остановку и ждёт автобус. Раньше она просто ждала и не знала, когда он придёт. Но теперь есть электронное табло, благодаря которому бабушка не знает ещё и что такое сервер, и почему он недоступен.

Это утечка: ошибка из мира кода попала в мир пользователя. Не надо так. Оборачивайте ошибки в понятную форму. Если нечего сказать пользователю — можно было бы вообще ничего не показывать.

В идеале сообщение об ошибке должно помогать пользователю решить его проблему. Об этом в следующем посте.

Про docops-подход к локализации пишет Дмитрий Симонов, CTO компании Дримсим.

Кроме перечисленных им платформ для локализации знаю ещё transifex.com и pootle.translatehouse.org

Если у вас есть опыт использования таких инструментов — поделитесь в @docsascode

Про локализацию софта
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.

— Польза от управления знаниями в компании.

— Управление знаниями в инженерных командах.