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

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

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

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

Статья будет полезна системным и бизнес-аналитикам и всем, кто работает с требованиями или процессами в команде.

Если вы хоть раз работали с такими сервисами, как Notion, Figma или Miro, то наверняка замечали (а может, и использовали) кнопку со звездочками и надписью «Create with AI». Она генерирует презентации, планы встреч, схемы и всячески упрощает жизнь пользователя. Но может ли такая фича помочь в решении более глобальных задач? Например, развитии сервиса или бизнес-процессов? Эту гипотезу мы и решили проверить. 

Меня зовут Даша Ронжина, я технический писатель Маркетплейса Cloud.ru. Наша команда внедрила нейросеть, чтобы помочь вендорам презентовать свои продукты на нашей витрине. В статье делюсь опытом, как можно быстро внедрить AI-решение путем промптинга, без датасетов и обучения модели. А также рассказываю, какие этапы мы прошли от идеи до выхода в прод. 

Заглядывайте под кат — если в вашем продукте тоже есть анкеты или формы, будет особенно интересно.

Меня побудило написать статью желание прежде всего поделиться файлом Excel, содержащим информацию о состоянии всех ГОСТов на текущий момент. О парсинге сайтов в открытых источниках, включая сам Хабр, достаточно информации. Кроме того, мне хотелось немного порассуждать о том, где и как можно применить эти данные и на что они могут повлиять.

Для проверки определенных типов данных я предлагаю парсинг сайтов, а автоматизация исправления уже на ваш вкус. Например, различные языки программирования. Лично я за весь свой опыт использовал: C#, Python, VBA для работы с Excel, в зависимости от ситуации.

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

Меня зовут Александр Панов, я занимаюсь разработкой документации в Test IT и хочу поделиться опытом имплементации такого бота. Расскажу, зачем он нам нужен, что он должен уметь, как мы его подключили и как он помогает улучшить документацию (а то и продукт). Еще обсудим цены и попробуем разобраться, обязательно ли редактировать промт.

## TL;DR

TypeSpec  умеет генерировать спецификации в форматах OpenAPI v3.0.0, Protobuf, JSON Schema.

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

Постановление Правительства 1135 описывает получение заключения для продукции, не имеющей аналогов в России. Заключение об отсутствии аналогов получают в Минпромторге по результатам экспертизы, проведенной одной из экспертных организаций. Пока количество полученных положительных решений небольшое. Например, по радиоэлектронным товарам — менее 30. Мы ожидаем рост количества обращений в ближайшее время.

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

Кому и зачем требуется заключение об отсутствии аналогов

Условия, этапы получения заключение об отсутствии аналогов

Как получить обнуление НДС при ввозе продукции, не имеющей аналогов в России

Закупка "недоверенного" ПАК для КИИ

ПАК в Минцифре с “железом” по ПП РФ 1135

Зачем заключение по постановлению 1135 претендентам  на СПИК

Итоги

Привет! Меня зовут Максим Соколов, я — аналитик в команде “Управление доступностью товаров и категорий”. В нашей команде была выделена отдельная подгруппа, которая создавалась специально под новый продукт-фичу для селлеров. Сразу стало понятно, что для реализации нового функционала требуется разработка нового микросервиса. Командой разработки было принято решение интегрироваться по gRPC, но мне до конца не было понятно, почему выбор именно такой. И тут я решил разобраться подробнее!

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

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

На свете много статей про проектирование API, в которых описаны архитектурные стили, протоколы, технологии. Информации — огромное количество, иногда она даже противоречивая, поэтому новичку тяжело подступиться к теме.

В этой статье я хочу дать точку входа для джун/мидл системных аналитиков, которые хотят разобраться в межсервисной интеграции. Мы пройдёмся по HTTP, REST, RPC и gRPC, разберёмся в их значениях. Выясним, почему эти аббревиатуры появляются, когда происходит проектирование API, и попробуем понять, когда и что следует применять.

Также по ходу статьи буду оставлять ссылки на хорошие (по моему мнению) статьи для более глубокого погружения в поднимаемые темы.

Вопрос о необходимости документации при разработке вызывает много споров. В динамичном мире IT, где изменения стремительны, я часто слышал холиварные обсуждения: а так ли необходима документация?

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

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

Полагаю, что с проблемой выбора удобной формы обзора сталкивались многие технические писатели, обозреватели и заказчики обзоров. С мутными по содержанию, плохо структурированными, трудночитаемыми обзорами бились чуть ли не все читатели.

В данном методологическом обзоре описаны назначение, цели, таксономия, классификация и общая структура обзоров.

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

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

В сентябре 2024 года с российского рынка ушли такие сервисы, как Miro и Notion, а перед этим российский рынок покинула Atlassian с продуктами Confluence и Jira. Меня зовут Павел Мокеев, я работаю системным аналитиком в компании МойСклад и я предлагаю поговорить о том, как базы знаний подверглись риску потери и что сделать, чтобы это не повторилось.

Привет! Меня зовут Сергей Востриков, я руковожу направлением Маркет и интеграций в Битрикс. Иными словами, я помогаю развивать функционал Битрикс24, доступный для разработчиков тиражных решений и индивидуальных кастомизаций. Это значит REST API и всё «вокруг» него — документацию, витрину Битрикс24 Маркет, кабинет разработчика решений и т.д.

REST API Битрикс24 включает в себя просто страшно сказать сколько методов, событий, встроек виджетов и прочих нюансов. Без документации с этим, конечно, совершенно невозможно иметь дело. И хотя нельзя сказать, что документации у нас не было, надо признать, что с течением времени у разработчиков накопилось к ней немало претензий.

Недавно мы показали сообществу разработчиков нашу новую документацию и, наконец, можем рассказать о том, как появился этот проект, как мы над ним работали и что планируем делать дальше. 

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

Добавлю, что  в требования к третьей версии Rest API, которая (спойлер!) сейчас находится в разработке,  мы заложили автоматическую генерацию документации из исходного кода продукта, вместо того чтобы продолжать вручную писать таблички с описанием методов.  

Однако ждать выхода нового Rest API мы не стали — нам предстояла долгая работа, мы решили подготовиться заранее. Кроме того, текущую версию REST API мы будем поддерживать еще долго, так что хорошая документация для неё всё равно нужна.

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

Пару раз на предыдущих местах работы я попадал на проект, где не было документации. Все знания о проекте были у разных коллег, а некоторые части систем вообще были «чёрными ящиками».

Что делать, когда попал в проект без документации? Ответ простой — уходить!

А если серьёзно, отсутствие документации — возможность для прокачки хардов и софтов. Мне приходилось собирать информацию по крупицам и минимизировать bus‑фактор. В статье дам пошаговую инструкцию, чтобы облегчить жизнь тем, кто попадёт в аналогичную ситуацию.

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

Привет, Хабр! Меня зовут Паша Абдюшев, я занимаюсь развитием продуктов в HFLabs. А где продукты, там и документация. С одной стороны, её ведение — вопрос явно не первостепенный. А с другой — неактуальная  информация не только бесит печалит, но и влечёт за собой дополнительные траты. 

Не спешите кидаться тапками, если тема кажется слишком очевидной. Иногда чужой пример — лучший стимул взять и наконец сделать это у себя. 

Наш путь по приведению в порядок накопившейся документации можно разделить на две части. Сначала мы прошлись по ней в ручном режиме, потом запустили автодокументацию. Я расскажу, что и зачем мы делали вручную, поскольку без этой части работы автоматизацию запускать смысла нет. Во второй части статьи будет непосредственно про автодоку. 

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

Осталось еще 5 пунктов.

Привет, Хабр! Меня зовут Роман Остапчук, я директор по техническому развитию РТК-Сервис. Одной из важных моих задач является взаимодействие с нашими заказчиками – телеком-операторами разного профиля и из разных сегментов рынка.

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