Вчера по приглашению Семёна Факторовича прочитал лекцию на его курсе по разработке технической документации. Поделился мыслями о парадигме DocOps. Во многом это адаптация DevOps к задачам и процессам документирования: общие с разработкой инструменты и процессы, в которых писатели отчасти становятся разработчиками, админами и дизайнерами; а те, в свою очередь, становятся писателями.

Вот запись лекции: https://www.youtube.com/watch?v=xo6pAFZ135I

А вот курс Тома Джонсона по документированию API: http://idratherbewriting.com/learnapidoc/index.html. Основная часть курса посвящена REST API — интерфейсам для взаимодействия между приложениями по сети. Есть раздел и про «библиотечные» (native library) интерфейсы — внутри приложений и на уровне программного кода.

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

Предлагаю вместе проходить курс и делиться опытом. Если хотите научиться документировать программные интерфейсы — присоединяйтесь. Напишите мне (@Nick_Volynkin). Начнём сразу, как опубликую перевод.

Конечно, мы любим документацию!

Отличная подборка текстовых форматов для диаграмм и схем. Спасибо автору! В целом канал @lovely_it_hell полон годных мыслей, очень рекомендую.

Я знаю, некоторые из вас любят документацию и схемки настолько же сильно, как я.
https://modeling-languages.com/text-uml-tools-complete-list/
Вот вам интересная ссылка с подборкой инструментов по визуализации UML

Конференция CodeFest опубликовала записи выступлений: https://2018.codefest.ru/program/.

Есть интересный доклад про использование чатбота-ассистента для доступа к базе знаний. https://2018.codefest.ru/lecture/1370/

​​txti.es

txti.es — cайт для публикации одностраничных документов c акцентом на скорости и малом размере страниц. Примерно как telegra.ph, но не совсем такой же.

Текст в txti.es пишется в разметке Markdown. Когда вы впервые сохраняете документ, сервис даёт ему случайный адрес, но можно выбрать свой. Чтобы потом редактировать документ, нужен пароль — “edit code”. Его сервис тоже выдаёт, и тоже можно задать свой.

Тест на поддержку Markdown

Проверил, что у txti.es с поддержкой Markdown. Вот мой тестовый документ: txti.es/markup-test, здесь подведу итоги.

Разметка для обычных текстов работает, кроме блока цитаты. Вложенные списки работают — а в telegra.ph я их не нашёл. Картинки и видео можно вставлять только со сторонних сервисов — сами не хостят. По умолчанию картинки на странице не показываются, нужно нажать кнопку. Всё для быстрой загрузки!

С оформлением кода большие проблемы: в блоках кода строки слипаются, кавычки заменяются на ".

Тест на размер и скорость

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

txti.es: 2 запроса, 2,6 килобайта.

​​telegra.ph: 17 запросов, 293 килобайта — в 100 раз больше!

Выводы

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

#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 сильно помогает нам с митапами в Новосибирске. Спасибо за поддержку!

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

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