О пользе Python в работе технического писателя: http://getdocument.ru/2019/07/24/why-python-is-good-for-technical-writer/

Что делать техписателю в первые дни на новой работе: http://getdocument.ru/2019/07/25/what-to-do-at-new-place/

Про DocOps-митап: http://getdocument.ru/2019/07/31/docops-meetup/

Труды техписателя: Quickstart: http://getdocument.ru/2019/07/31/techwriter-output-quickstart/

Как быстро установить zsh: http://getdocument.ru/2019/08/01/how-to-install-zsh/

31-го августа в Новосибирске пройдёт 12-й Конвеерум. Подробности: http://getdocument.ru/2019/08/06/konveerum-no-12/

На этой неделе я познакомился с редактором Markdown-кода http://hackmd.io. Удобный редактор: можно писать документы в любимом формате Markdown, сохранять их и экспортировать результат в несколько форматов, включая HMTL. В формат PDF вроде тоже можно, но я не нашёл такой опции.
Cписок возможностей доступен на странице: https://hackmd.io/features

Девятнадцатого октября в Ижевске пройдёт Удмуртская Интернет-конференция UIC DEV.

Одним из спикеров на конференции будет Евгений Галактионов, наш коллега и ведущий инструктор по системному анализу.

Коротко о выступлении Евгения:

опыт работы системным аналитиком в проекте по созданию системы учета работы автотранспорта для одного из крупнейших регионов РФ показывает, что задача проектирования отчета далеко не всегда тривиальна.

Может получиться, что невозможно без дополнительной доработки всей системы получить нужную отчетность. А любая доработка – это дополнительные затраты времени и денег, а следовательно, возможные конфликты между заказчиком и исполнителем.

Основные ситуации, когда невозможно получить нужные отчеты:
1. Данные для получения отчетов отсутствуют в системе, так как не были спроектированы процессы по внесению исходных данных.
2. Данные присутствуют, но непонятно, а эти ли данные нужны для формирования отчета и как это проверить?
3. Данные есть, но их так много, что попытка провести выборку и расчет для получения отчета требует многочасовых расчётов, а может и просто привести к зависанию системы.

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

👉 Купить билет на конференцию: http://short.picom.su/zvufUo

Как я учусь документировать API

Прежде всего, нужно понять основы. Для этого есть прекрасная книга «An Introduction to APIs», которая доступна по адресу https://zapier.com/learn/apis/. Она знакомит с нужными терминами и объясняет много полезных вещей. Её достоинство в том, что она небольшая и ты не успеешь устать.

После того, как теория стала понятна, можно переходить к курсу Тома Джонсона: https://idratherbewriting.com/learnapidoc/contact.html

Перевод курса Тома, выполненный Денисом Старковым, доступен по адресу https://starkovden.github.io/

Опубликованы записи докладов и слайды недавней конференции API the Docs: https://pronovix.com/event/api-docs-amsterdam-2019.
Там всё про документирование кода и API.

Спасибо @aselivanava за ссылку :)

На днях я закончил читать книгу Docs Like Code, автор Anne Gentle.

Книга содержит очень много полезного про docs as code. Нет смысла пересказывать всю книгу, поэтому я опишу те моменты, которые заинтересовали меня.

Документация и код

Чем дальше документация от кодовой базы, тем сложнее её обновлять. Заведите за правило, что merge кода невозможен без актуализации документации.

Если документация находится в одном репозитории с кодовой базой, то workflow должен совпадать с разработкой кода.

В чём docs as code выигрывает у Wiki

У docs as code можно лучше приспособить к бизнес-процессам.

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

И как процесс будет меняться с ростом команды.

Про CI/CD

CI/CD системы нужны, если документация постоянно меняется и над ней работает большая команда. Не каждый сможет заходить на сервер и запускать скрипт обновления. Опять же, постоянная сборка сокращает время, которое нужно для каждой сборки по отдельности.

Про вычитку

Для вычитки можно использовать Gerrit. Я не пробовал, но интересно.

Как убедить руководство внедрить docs as code в компании

Собрать современный адаптивный сайт с документацией и дать посмотреть его руководству.
Настроить технологии CI/CD для сборки документации. Сюда же можно подключить тесты и линтеры.
Подключить метрику и оценивать, как пользователи читают документацию и всё ли им понятно.

Git очень нужен, если технический писатель работает в парадигме docs as code.

1. Фундаментальный труд про Git, который можно читать много раз и каждый раз открывать что-то новое:

https://git-scm.com/book/en/v2

На мой взгляд, лучше скачать книгу в формате PDF.

2. Отличный тренажёр по Git, который поможет познать всё его могущество:

https://learngitbranching.js.org/

Первая встреча системных аналитиков в Томске

Встреча пройдёт 7-го декабря с 11 до 14 часов в пространстве «Точка кипения», по адресу Проспект Ленина 26, г.Томск.

Одним из спикеров будет Евгений Галактионов, ведущий инструктор в Школе Системного Анализа и участник квартирника «Почему технический писатель не аналитик». Также будут выступать аналитики регионального центра развития «Томск».

Темы, которые будут обсуждаться на встрече:

- взаимодействие аналитика с заказчиком,
- отчёты как источник функциональных требований,
- специфика профессии.

Официальная ссылка на страницу мероприятия: https://leader-id.ru/event/32328

Напоминаю, что 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. Зарплата выплачивается в долларах США.