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

Вложенность. Для хранения изображений я создал структуру папок, и в каждой хранил скриншоты для соответствующего раздела. Например, папка для раздела “Сообщения” называлась s-messages.

Именование. Скриншотам внутри папки я давал имя папки и порядковый номер. Например, первое изображения для раздела “Сообщения” называлось s-messages_01.png, второе s-messages_02.png и так далее. Удобно, потому что не нужно придумывать осмысленное название для каждого.

Автоматизация. Довольно скоро я устал делать снимок, переименовывать файл, присваивать ему порядковый номер и сохранять в нужную папку. Это приводило к ошибкам. Поэтому я разработал скрипт на Python, который переносит файл в нужную папку, переименовывает и присваивает порядковый номер и копирует в буфер обмена полную ссылку на файл в формате Markdown. И ещё один скрипт, который избавляет папку от ненужных файлов и указывает на "битые" ссылки внутри документа.

Требования к скриншотам я изложил в отдельном руководстве по стилю. Да-да, в этом случае нужен style guide для изображений. В нём можно указать:
• параметры у изображения,
• визуальные эффекты и их настройки,
• очерёдность вставки – до или после поясняющего текста,
• поведение, если скриншот делится на две или более части. Например, если у окна есть прокрутка и не все поля помещаются в один снимок.
• тип снимка. Смотри ниже.

Снимки могут быть двух типов:

• фотографируется вся рабочая область приложения с использованием затенения или маски. Хорош тем, что пользователь всегда видит, в какую часть экрана смотреть. Не нужно искать кнопку или поле по всему экрану. Недостаток в том, что придётся переделывать все скриншоты, если появится элемент, одинаковый для всех снимков. Например, новый пункт главного меню или логотип в правой верхней части экрана. Ну или “дорисовывать” нужное с помощью библиотеки ImageMagick.

• фотографируется только описываемая область экрана. Тут всё просто – вырезал кусок из рабочей области и сохранил изображение. Недостаток подхода в том, что пользователь будет искать нужное по всему экрану. Да и вообще, куски изображений в разных разрешениях выглядят некрасиво.
Я использовал первый вариант.

Размер окна у приложения можно настраивать с помощью скрипта. В Windows можно написать скрипт на Visual Basic, в MacOS есть AppleScript, в Linux наверное можно написать скрипт на Python. В этом случае все снимки выглядят одинаково и понятно.

Всем привет! Я работаю техническим писателем в компании NXLog и мы ищем технического писателя к нам в команду. Официальное описание вакансии ниже:

Location: Remote

We are looking for a Technical Writer who can help us enhance our product manuals, user guides and other documentation as well write blog posts. The ideal candidate is an experienced IT professional who is keen on creating technical content. The job would also involve researching NXLog integration with third party solutions and shiny new tech that emerges. System administrator skills are a great plus but most importantly you should be a quick learner and eager to understand new technologies.

Requirements:

- Experience with modern documentation formats (asciidoc, docbook, markdown).
- You know what version control is and have used Git before.
- Sysadmin/DevOps skills on Linux and Windows.

Nice to have:

- Experience with log management tools and SIEM products (QRadar, ArcSight, Splunk, Snare, syslogd, Logstash, Kafka, Scribe, ELK, Graylog, etc),
- Experience with *BSD, Solaris, AIX, HP-UX, MacOS

Please do not apply if you are the type of Technical Writer who likes to pass around MS Word documents in email.

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

Готов рассказать о вакансии и моих впечатлениях, пишите в личку @a_samaranche

P.S. Зарплата выплачивается в долларах США.

14 мая вечером Евгений Галактионов, ведущий инструктор Школы системного анализа, расскажет, как отчеты помогают системному аналитику с выявлением функциональных требований и проектных решений https://sysanschool.timepad.ru/event/1308815/

Всем привет. Стала доступной запись с zoom-встречи, где Евгений Галактионов подробно рассказал о роли отчётов в системной аналитике. Отчёты - это один из базисов в формировании требований к программному продукту. Мне понравилось, что Евгений подробно рассмотрел отчёты, разные рабочие ситуации и предложил решения. Рекомендую к просмотру всем, кто работает с требованиями. Видео доступно по ссылке:
https://www.youtube.com/watch?reload=9&v=TpMYTV-xQN4.

Мой отзыв на курс по системной аналитике в Школе системного анализа: http://getdocument.ru/2019/07/05/software-requirements-course-feedback/

Партнёры попросили разместить:

Самое яркое аналитическое событие года онлайн! 26-27 июня! Не пропустите!

Каждый год мы собираем аналитиков, руководителей проектов, предпринимателей, владельцев бизнеса и топ-менеджеров. Практическая ценность докладов, полезные знакомства, позитивная и уютная атмосфера — самые главные принципы фестиваля!

В этом году вас ждет новый формат проведения фестиваля — онлайн! В течение двух дней будут проведены доклады от ведущих специалистов-аналитиков, консультантов и тренеров. В нашем онлайн-фестивале может принять участие любой желающий! Подойдет и новичкам, и профессионалам своего дела, каждый найдёт для себя что-то по душе! А после конференции вас ждет afterparty в Zoom со всеми участниками и докладчиками, где каждый сможет задать интересующий вопрос и высказать свое мнение. Будет интересно!

📍Участие бесплатное — просто зарегистрируйтесь на сайте https://lafest.ru/

Если остались вопросы по организации и проведении мероприятия пишите на почту lafest2020@gmail.com или звоните по бесплатному номеру 8-800-6000-868

Почему я ушёл от Atom обратно к VS Code

Дано: технический писатель, разрабатываю документацию в Asciidoc, всё люблю "из коробки", два года работал с VS Code, затем по рекомендации коллег перешёл на Atom.
Несколько месяцев проработал с Atom и вернулся обратно к VS Code, ниже делюсь впечатлениями.

В Atom отсутствуют рабочие пространства. Ну или я их не нашёл.

Git Blame в Atom есть только в виде таблицы, не нашёл GitLens, чтобы прямо над каждой строкой было.

Установленный терминал, а встроенного терминала в Atom нет, игнорирует символ _ в названиях веток и тексте.

Установленный терминал открывается с помощью Ctrl+Shift+T, но как его закрыть обратно? Такого хоткея я не нашёл, ну или плохо искал. В VS Code всё решается одним хоткеем.

Иногда Atom "вылетает" без объяснения причин. Мелочь, но отвлекает.

Чтобы установить новый Package в Atom, нужно зайти в Welcome Guide и только там выбрать Install a Package. Какой-то сложный UX.

Время от времени Atom плохо индексирует проект, и зачастую невозможно найти файл сразу после запуска Atom. Иногда дело доходило до использования grep.

Не нашёл удобный package для работы с TODO в Atom.

Непонятно, какой комбинацией клавиш в Atom можно перенести окно вправо вместо того, чтобы нажимать на окно правой кнопкой и выбирать Split Right.

Внешний вид в VS Code просто приятнее. Но это вкусовщина.

Поиск команды и файла разделены разными комбинациями в Atom. В VS Code это сделано в одном окне.

Asciidoc preview - невозможно обновить окно, чтобы посмотреть изменения. Сам предпросмотр обновляется не сразу, я не понял логики обновлений.

Asciidoc preview - не пролистывает исходный файл при прокручивании Preview.

Asciidoc Preview - не показывает JSON при include.

После переключения на другую ветку, Atom метит файлы с прежней ветки как несохраненные и спрашивает, сохранить ли. Иногда это сбивает с толку. VS Code же помечает файл как удалёнынй и ничего не предлагает с ним делать. Это удобнее.

Преимущество Atom: более насыщенный цветами синтаксис Asciidoc, лучше обозначены элементы контента. В VS Code цветовая гамма скромнее.

Общие впечатления: Atom хороший редактор, но VS Code мне нравится больше и он субъективно удобнее.

Небольшая шпаргалка по Graphviz, где я рассказываю о неочевидных моментах при разработке диаграм:

http://getdocument.ru/2020/06/27/unobvious-in-graphviz/

Пиши проще

17-го сентября 2020 года, в 18-00 МСК будет доклад "Пиши проще". Выступать буду я, Антон Самарин, технический писатель в компании NXLog. Покажу простые приёмы, которые улучшают техническую документацию на уровне документа, абзаца, и предложения.

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

Ссылки для регистрации будут чуть позже.

Ссылка для регистрации на доклад "Пиши проще":

https://sysanschool.timepad.ru/event/1427811/

Ссылка на YouTube, где будет проходить трансляция:

https://www.youtube.com/watch?v=4nXYweoVJiE

Вебинар Пиши проще

Ссылки на презентацию и запись вебинара :

http://getdocument.ru/2020/09/17/write-it-easy-links-to-materials/

Всем привет! Ищем себе коллегу-техписателя в компанию NXLog.

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

Что мы делаем
Разрабатываем документацию для раздела https://nxlog.co/documentation
Посмотрите её чтобы лучше понять работу. И посмотрите язык, на котором она написана.

Условия труда
Удалёнка, почасовая оплата труда в долларах США.
Работаете когда хотите: в любое время суток, в любой день недели. Главное - отработать нужное количество часов в течение месяца.
Оплачиваемый отпуск.
Международная команда людей, приятно общаться и обращаться с вопросами.
Основной состав находится в Венгрии, поэтому живём по европейскому времени. Никаких ночных созвонов :)

Оплата труда
Деньги переводят на банковский счёт один раз в месяц. Без задержек и отговорок.
Можно работать в статусе самозанятого и платить 6% от поступления, если вы из России.

Что нужно для работы
- Отсутствие страха к разным штукам, преимущественно из мира Linux. Примеры из моей практики: osquery, Nagios Log Server, Microsoft ATA, Linux Audit System, Docker, Windows EventLog, Systemd, много их.
- Отсутствие страха к разным операционным системам: Linux, Windows, очень редко FreeBSD.
- Иметь приемлемый уровень английского. Native level не нужен, поскольку ревью делает коллега из США, и нам до него далеко.
- Скиллами сисадмина обладать не нужно. Но нужно быть готовым всегда изучать новые технологии и постоянно развиваться, на это в компании дают достаточно времени.
- Компьютер с 16Гб оперативки чтобы запускать виртуалки. Иногда нужно сразу работать с тремя виртуальными машинами.

Как построена работа
- Заходим в Gitlab, берём задачу, работаем.
- Создаём merge request, делаем коммиты.
- Если нужно, тестируем NXLog, описываем результаты, делаем коммиты.
- Назначаем задачу для ревью.
- Исправляем контент после ревью. Передаём его для слияния в master.
- Через 2-3 недели видим результат работы в открытом доступе. Можно показывать свою работу родным и близким, без всяких NDA :)

Наши инструменты
- Gitlab
- Asciidoc
- Git
- Редактор вроде Atom или VS Code

Контакты и адреса
С вопросами обращайтесь ко мне в Телеграм, @a_samaranche
Официальная страница с вакансией: https://nxlog.co/careers

Город ИТ

Школа системного анализа и Евгений Галактионов, в этом году, в рамках конференции Город ИТ будут проводить тематическую секцию "Системный анализ". Приходите, будет интересно.

Подробности: https://gorod.it/20/analysis

Всем привет.

24-го и 25-го апреля этого года Школа системного анализа и проектирования проводит онлайн-конференцию SYSTEMS x DESIGN: Проектирование успешных IT-систем.

Подробности о конфереции и приглашённых экспертах - по ссылке .

Всем привет! Из понравившегося за последнее время, ну т.е. за последние 1,5 - 2 года:

1. Хороший материал от DIVIO про типы документации и организацию, очень полезно: https://documentation.divio.com/
Впечатления: после просмотра видео я наконец-то начал понимать и различать типы документации.

2. Бесплатный курс по английскому языку для технических писателей от Stepik: https://stepik.org/course/684/promo
Впечатления: вначале кажется скучным, но процесс познания начинается со второй половины курса.

Остаёмся на связи :)

12 апреля, во вторник вечером, встречаемся на новом канале и слушаем продолжение лекций посвященных памяти Ф.П. Тарасенко и П.Ф. Тарасенко.
Ярослав Лопухин расскажет про Технологию решения проблем которую предлагает Прикладной системный анализ.
https://sistemnyy-podkhod.timepad.ru/event/1983546/

28-29 мая состоится CodeFest 12 - крупнейшая за Уралом конференция для ИТ-специалистов.
В этом году на конференции будет целый ряд выступлений по тематике системного и бизнес-анализа.
Из выступлений можно будет узнать:
- Как аналитику планировать свою работу в рамках проекта;
- Какой набор артефактов лучше всего создавать при разработке требований к информационным системам;
- Как ТРИЗ может помочь при проектированию ИС.
На подходе в программу ещё несколько выступлений по актуальным для аналитиков темам .
Так же можно будет поучаствовать в дискуссии про то, чем отличаются анализ и аналитика, и к чему ведёт путаница при использовании этих понятий.
И главное! Это можно будет пообщаться и обменяться опытом!

Итак, представляю вам новый телеграм-канал для тех кто интересуется системным подходом, прикладным системным анализом и другими системными дисциплинами, а также практикой их применения в ИТ.

Встречайте: https://news.1rj.ru/str/systemspodhod