Подготовка технической документации *

Работая с менеджерами в сфере ИТ, обнаружил, что часто отсутствует системное представление о видах инфраструктуры, которая необходима для развертывания автоматизированных систем (АС). Вследствие этого возникают ошибки в планировании разработки и развертывания АС — некоторые виды инфраструктуры упускаются из внимания: не учитываются в проектах, не запрашиваются технические условия, не согласовывается использование, отсутствуют договоры на использование нужной инфраструктуры и т. п. Также возникают ошибки в распределении ответственности при эксплуатации развернутой АС, когда часть инфраструктуры оказывается «ничейной», потому что о ее обслуживании забыли договориться.

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

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

В моем опыте был случай, когда интеграция представляла собой связку около 15 систем, каждая из которых имела свою базу данных. Все сервисы разворачивались в k8s вручную, тестовые данные были неконсистентны, интеграции между сервисами приходилось настраивать вручную самостоятельно. Ни один сервис нельзя было замокать: каждый элемент влиял на тестируемую бизнес-логику. Я просто познавала дзен, разбираясь во внутреннем устройстве систем и следуя заранее составленному тест-плану. 

Меня зовут Катя Назмеева, сейчас я тестирую бэк в Lamoda Tech. В статье я предложу стратегии для успешного проведения интеграционного тестирования микросервисов и расскажу про инструменты, которые могут облегчить этот процесс. Обсудим, как организовать все таким образом, чтобы интеграционное тестирование не создавало задержек в новых релизах — и не заставляло QA страдать.

Привет, друзья-аналитики!

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

Введение

Представление моделей бизнес‑процессов на основе онтологий (онтологическое моделирование) эквивалентно Semantic BPM. Введение в семантический BPM (Business Process Management) см. «Semantic BPM. Семантика и синтаксис бизнес‑процессов» [semBPM24]. Если кратко, то можно провести аналогию: если классическая BPM система (BPMS: ARIS, бизнес‑студия, fox‑manager и т. п.) — это технологический аналог mediawiki (wikipedia), то Semantic BPM — это технологический аналог semantic mediaWiki (Wikidata), т. е.

IF MediaWiki → Semantic MediaWiki then BPM (ARIS, BPMS, EA) → Semantic BPM

Основной замысел (цель) семантического представления процессов (BPM, EA) не классическими BPM‑системами, а семантическими (Linked Data) — такой же, как и у семантических wiki

Одно из ключевых дополнений к wiki‑гиперссылки (html) это указание не просто что «ОбъектА связан с ОбъектомБ» (т. е. просто «связано») и соответствующий кликабельный переход (wiki‑ссылки, markdown syntax), а указание, что «ОбъектА связан с ОбъектомБ» такими‑то типом отношения (впрочем, как и задание других свойств объекта через отношения).

Изначально все BPMS (изначально называемые CASE‑средствами) — семантические, т.к. их суть — это отношения между объектами, только в них семантика глубоко спрятана «под капотом» BPMS и нестандартная (собственная, проприетарная). Semantic BPM «поднимает» семантическую составляющую на поверхность (возможность работы с семантическим слоем) и использует стандартные сематические технологии Linked Data.

В основе RDF (Resource Description Framework) — триплеты «субъект — отношение — объект» лежит ERD: Entity Relationship (ER) diagram. RDF \ ERD — это способ формализации знаний на основе атома знания — триплета. Вообще ER, subject, predicate, типы рассуждений и другие базовые элементы для работы со знаниями в СССР содержались в школьных учебниках [Логика54].  

Слышали фразу: «Нет тз — результат хз»? А ведь в нем столько правды! Правильно составленное техническое задание помогает избежать недоразумений между заказчиком и разработчиком, чтобы на выходе проект получился таким, как вы планировали в самом начале.

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

Влияет ли наше состояние на то как мы думаем и что говорим? Как через состояние и мышление повысить качество документации?

Приветствую всех! Меня зовут Катя Фролова, я работаю техническим писателем в RuStore.

В прошлом году документация RuStore переехала на новый движок.

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

Всем привет. Меня зовут Татьяна Цикунова, я работаю системным аналитиком в компании МойСклад, в команде eCommerce. Моя команда специализируется на разработке интеграций сайтов с сервисом МойСклад. Мы помогаем бизнесу автоматизировать процессы: учета, продаж, коммуникаций с клиентами, выход на новые торговые площадки. Также мы разрабатываем интеграции с самыми популярными маркетплейсами на рынке России и зарубежных стран У МоегоСклада уже есть решения для селлеров на Ozon, Wildberries, Яндекс Маркете и Мегамаркете, а также для зарубежных маркетплейсов.

В статье я расскажу о том, что такое эти самые интеграции с маркетплейсами на примере сравнения наших решений для Ozon и Wildberries. 

Сначала приведу немного статистики от Data Insight. Чтобы понимать, насколько сейчас популярна торговля на маркетплейсах, достаточно взглянуть на слайды ниже. 

Как за 2 месяца создать самопополняемую документацию там, где ее никогда не было? Вот четыре этапа, которые нужно будет пройти техническому писателю.

Привет, Хабр! Меня зовут Виктория Юльская, и я старший системный аналитик в Ozon.

Я думаю, здесь найдётся много людей, которые хоть раз работали с документацией API в Confluence. Да-да, те самые километровые страницы на каждый метод — с описанием всего и вся в виде текста, таблиц, диаграмм последовательности и т. д.

Зачастую такая документация API в Confluence устаревает ровно в тот момент, как её закончили писать. После передачи задачи в разработку, как только что-то непонятно, куда все идут? Правильно, к аналитику — «А как это работает? А что это значит? А что если...?».

Ну вот же дока, там все написано... но обычно никто не хочет читать огромную доку на метод, быстрее же спросить. И зачастую у самих аналитиков есть вопросики по актуальности этой документации (уже есть новые договорённости со встреч, комментарии в документации и т. д.).

Есть ли более эффективный способ ведения и поддержания документации API в актуальном состоянии? Давайте разбираться.

Что такое Docs as Code классно описано в статье Docs as Code: введение в предмет.
В двух словах: это ведение документации на языке разметки (Markdown, AsciiDoc) с хранением в репозитории.
Плюшки — все вытекающие от работы с репозиторием.
Минусы — в этой статье.

На осенних Analyst Days прошлого года добрая четверть докладов была посвящена теме Docs as Code. На тот момент конклав аналитиков на моём прежнем месте работы уже 9 месяцев решал, нужен ли на проекте модный-стильный-молодёжный Docs as Code или всё же остаться в дышащем на ладан Confluence. К чему пришли — не знаю. На новом месте работы мы внедрили Docs as Code за неделю — было чёткое понимание проблематики, подход казался выигрышным решением. Используем полгода.

Без толковой API-документации сложно делать открытый продукт и ждать, что его будут развивать пользователи. Часто владельцы сервисов занимаются документацией по остаточному принципу. В итоге разработчику достаётся запутанная инструкция, а интеграция усложняется или просто становится невозможной.

Мы осознали эту проблему до разработки открытого API и заранее спланировали, как сделать документацию понятной. Сегодня расскажу подробно про портал документации Alfa API. Как с ним быстро разобраться в технической реализации, а главное — улучшить впечатления от работы со сложным продуктом — узнаете в статье.

У химиков есть известная байка, которую они любят рассказывать молодому поколению. Главный герой этой истории — студент, который пошагово воспроизводил методику одного химического эксперимента из учебника. Он старательно выполнил очередной шаг «добавьте азотную кислоту» и... в лаборатории прогремел взрыв! Когда впоследствии стали разбираться, в чём же дело, выяснилось, что на следующей странице учебника было написано: «... медленно, по каплям».

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

Как же лучше писать и оформлять примечания в технических текстах?

В статье расскажу про Foliant и про возможности по документированию HTTP API с его использованием. Упор сделаю на API, которые описываются с помощью OpenAPI/Swagger. Также вскользь коснусь возможностей по документированию API, описанных с помощью других спецификаций.

Привет техписам и всему ИТ-сообществу. На связи команда «Инферит Клаудмастер», и мы хотим рассказать вам о том, как мы организовали базу знаний о нашем продукте. Для этого мы поговорили с Миленой Балановой, техническим писателем Инферит Клаудмастер, которая в перерывах между «витанием в виртуальных облаках» и написанием документации рада поделиться инсайтами о создании базы знаний:

«Ваша документация — отстой!», «Я её никогда не читаю, всё равно там ерунда написана!», «Эти документаторы опять всё напутали», «Да любая нейросеть быстро напишет это в сто раз лучше», «Там никогда не найти ничего нужного», «А разве у нас есть документация?»

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

C вами Семён Факторович и компания documentat.io. С 2018 года мы помогаем IT-компаниям создавать техническую документацию: пишем документацию на заказ, консультируем инженерные команды по процессам документирования, учим техписателей и инженеров писать документацию.

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

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

В этой статье я расскажу об индустриях, в которых работают русскоязычные техписатели, о видах документов, которые они разрабатывают, о востребованности знаний ГОСТ и о том, как всё это влияет на техписательские зарплаты.

Всем привет, меня зовут Влад и я запилил собственный IT стартап в одиночку потратив $100. Я давно хотел проверить свои силы и показать самому себе на что я способен, смогу ли я дойти от: создания идеи, проработки ui/ux, разработки frontend & backend, до публикации продукта и его маркетинга.

Для общего понимания я постараюсь кратко описать свой background. В 14 лет я увлёкся веб разработкой поскольку у меня была команда по игре counter strike и для того чтобы заявляться на турниры, нам требовался сайт, по мере его поддержания, я освоил исскуство владения фотошопом. Этот сайт я начал монетезировать и смотрел как его можно продвигать.

Дальше был универ, где я много писал код на c++, python, c#, писал свои нейронки, программировал роботов, проходил алгоритмы и структуры данных. В это самое время вместе с друзьями начали развивать ивент стартап, который помогал пользователям узнавать расписание, изменения, следить за интересными спикерами. Я занимался ui/ux проектированием и frontend разработкой. В это самое время я изучил первые в своей жизни методологии дизайна: google material design guidelines and Apple Human Interface Guidelines.

Писал диплом на тему: примерка мебели в дополненой реальности на свифте.

Потом был момент, когда мы с партнёрами открыли it outsource компанию на 40 человек разработки, где я был CTO и следил за технологиями в компании на стеке: JS, Typescript, React, Vue, Php, python, nodejs, reactnative.

И весь свой накопленный опыт я хотел применить для создания продукта.

Привет, Хабр! Меня зовут Кирилл Рупасов. Я руковожу группой инженеров SOC (Security Operations Center) в «К2 Кибербезопасность». Я не понаслышке знаю, как порой непросто создавать контент для Центра мониторинга кибербезопасности. Написать одно правило обычно несложно, а вот разработать их связанный комплекс — задача достаточно трудная, особенно для молодых команд.

Под катом я собрал всю полезную информацию о грамотном создании контента: виды правил и их нюансы, workflow и возможные проблемы, сценарии обработки инцидентов. А также рассказал, как мы организовали процесс разработки и поддержки актуальности контента в своем коммерческом SOC.

Хабр, привет!

Меня расстраивает несправедливость в мире IT: для новичков-разработчиков есть куча пошаговых инструкций, о там, как разработать API или мобильное приложение. Хочу немного уровнять баланс вселенной, поэтому я написал небольшой гайд для аналитиков для составления документации.

В прошлой статье я представил шаблон, а теперь заполнил его для фичи «Экспресс-доставка товара в маркетплейсе». Моя цель – показать, как можно вести документацию и как правильно заполнять этот шаблон.