Напоминаю, что 7-го декабря пройдёт первый митап системных аналитиков в Томске.

Видео с анонсом предстоящей встречи:
https://www.youtube.com/watch?v=WIHi7XRuwDA&feature=youtu.be

В марте 2019 года на CodeFest 10 состоялся квартирник «Почему технический писатель не аналитик»: https://www.youtube.com/watch?v=h48ycbRFDsU, который собрал вместе системных аналитиков и технических писателей.

Хотя эта тема была больше про технических писателей, но большинством в зале оказались системные аналитики. Это значит, что аналитикам из Сибири не хватает на конференции своей площадки, где бы они могли обмениваться опытом и лучшими профессиональными практиками.

Недавно мы узнали, что организатор этого квартирника и просто наш хороший друг Евгений Галактионов вошел в программный комитет конференции. Это произошло благодаря поддержке Дениса Яковлева, программного директора конференции CodeFest.

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

Всех с Новым Годом :) В прошлом году мне нужно было задокументировать API, в котором сообщения идут в формате XML. Выбор пал на API Blueprint, потому что он выглядит легковесно и позволяет писать исходник в формате Markdown, чего не скажешь о Swagger или RAML.

По ходу работы выяснилось, что в API Blueprint удобно документировать ответы только в формате JSON, а вот с XML нужно придумывать обходные пути. Подробности - вот здесь, поскольку на сайте это выглядит более читабельно.

Всем привет :) В этом году канал getdocument пережил «взрывной» рост аудитории - c 25 до 73 подписчиков в течение первых дней благодаря ссылке с канала DocOps.

Хочу представиться: меня зовут Антон Самарин, я автор канала getdocument и технический писатель в компании РТК Инфотех. На канале я делюсь опытом, который хочу запомнить и использовать в будущем. Для этого я пишу шпаргалки на сайте getdocument.ru и рассказываю о них на этом канале. Например, я очень люблю шпаргалку про Zsh, потому что с её помощью можно быстро установить и настроить эту оболочку.

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

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

Уже 29 февраля состоится новая встреча, которую организуют Евгений Галактионов («Школа системного анализа») и Региональный центр развития «Томск» Банка России.

Участники встречи:

Евгений Галактионов («Школа системного анализа») ответит на вопрос: «Кто такие системные аналитики и почему их постоянно путают с бизнес-аналитиками. Чем они отличаются и кто из них круче».

Марина Киселева («Битворкс») сделает доклад «Пользовательские истории в теории и на практике» про то, как аналитики используют этот инструмент выявления и фиксации требований в проектах разработки программного обеспечения.

Евгений Мирошниченко («Rubius») реализует предложение, которое он сделал на встрече в декабре и расскажет о сложных заказчиках, с которыми аналитик взаимодействует на проектах. И совместно с участниками встречи попробует выработать способы работы с такими непростыми заказчиками.

Встреча будет проходить 29 февраля 2020 года по адресу г.Томск. ул.Ленина 26, «Точка кипения».
Ссылка для регистрации на мероприятие.

Коллеги, есть обновление по встрече 29-го февраля в Томске.

Состав спикеров немного изменился, и теперь вместо Марины Киселёвой будет выступать Татьяна Ларина ("Центр Финансовых Технологий") с докладом "Как масштабировать работу Аналитиков, опыт одной компании."

Татьяна расскажет о проблемах, с которыми в условиях быстрого роста столкнулось подразделение компании в попытке использовать отлаженные процессы разработки, а также о влиянии роста компании на эффективность работы.

Почти год я работал над пользовательской документацией с большим числом скриншотов – несколько сотен на полуторатысячный документ в формате 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/