getdocument

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://learngitbranching.js.org/

На днях я закончил читать книгу 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 для сборки документации. Сюда же можно подключить тесты и линтеры.
Подключить метрику и оценивать, как пользователи читают документацию и всё ли им понятно.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

"Впервые в рамках концеренции "Город ИТ"( https://gorod.it/), 7 сентября, будет проведена секция по Системному анализу в ИТ. У кого есть знакомые аналитики в Сибири или есть интерес к работе аналитиков - приходите."

Channel name was changed to «getdocument»

Отзыв на курс по системной аналитике