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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В конце статьи вы найдете сводную таблицу со всеми инструментами.

Всем привет! На связи «Инферит Клаудмастер». Я Милена, технический писатель, и пару месяцев назад уже делилась в статье, как в две руки актуализирую портал документации, чтобы вся информация в нём была актуальная и полезная.

На этот раз хочу рассказать:

- о том, почему ченджлог и роадмап — пользовательская документация,

- о ключевых преимуществах ведения обоих видов документации,

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

Бывает так, что через n-месяцев после успешной сдачи прошлого (а может, уже позапрошлого) проекта, приходит руководитель проектов с вопросами: «А работает ли функциональность?», «Почему одни организации ей пользуются, а другие нет?», «На всех ли организациях функциональность настроена верно?», «Как узнать, что именно и в каких организациях не настроено?».

В одном из таких случаев на проверку 90 организаций региона мы потратили более 9 часов! Меня зовут Александр Шипачев, я руководитель отдела контроля и качества внедрения БЦ Медицина. В этой статье расскажу, как мы создали инструменты проверки корректности настроек системы и что из этого вышло.

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

В этой статье я буду рассуждать о графических артефактах в технической документации. О том, какие существуют визуальные языки, о подходе «docs as code», задачах которые нужно решать применительно к графике в рамках этого подхода и инструментах которые пробовал использовать. Также рассмотрю возможные, на мой взгляд, улучшения процесса работы с графическими артефактами и расскажу о попытке спроектировать и реализовать свой собственный язык разметки.

Привет, Хабр! Я являюсь тестировщиком компании TravelLine. Мы разрабатываем единую систему для гостиничного предприятия, которая помогает отелям, санаториям и другим средствам размещения автоматизировать бизнес-процессы.

В тестировании своих продуктов мы придерживаемся подхода «Shift Left» или «Сдвиг влево». Суть этого подхода — смещение фазы тестирования влево в жизненном цикле продукта и проведение тестирования на каждом этапе разработки. Одной из техник, которая помогает смещать тестирование влево является тестирование документации и требований.

Привет, Хабр.

Знаю, что здесь куча обзоров на различные курсы от разных школ, платформ и иже с ними. Но все-таки хочу вставить и свои 5 копеек. Рассказываю о своих ощущениях от курса «Системный аналитик», который я (успешно) окончил в августе 2024 года.

Почему я вообще в это все ввязался?

Привет, Хабр! Меня зовут Сергей Махнаткин, я работаю разработчиком в отделе User Experience в Yandex Cloud. В прошлом году мы писали о нашей дизайн-системе и библиотеке компонентов Gravity UI. С тех пор система не раз обновлялась и обрастала новыми функциями, и сегодня я хочу рассказать о новом инструменте — Markdown Editor, который значительно упрощает процесс работы с документацией.

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

В процессе разработки проектного решения мы, как правило вносим множество изменений. Нет, конечно есть проекты, где все требования жестко «приколочены гвоздями» в ТЗ и внесение каких‑либо изменений практически невозможно. Но большинство проектов в той или иной степени используют знаменитую методологию Agile, позволяющую проявлять гибкость при реализации проектов.

При этом, мы не всегда можем четко определить, какие из принятых нами решений в процессе работы являются архитектурными, то есть требующими обязательного документирования, а какие таковыми не являются, хотя также очень важны для проекта. Когда архитектура программного обеспечения развивается в результате принятия командой ряда решений, командам разработчиков требуется способ отслеживать принятые ими архитектурные решения. И здесь им на помощь приходит отчет об архитектурных решениях Architecture Decision Records (ADR). По сути, ADR — это документы, которые описывают принятые архитектурные решения в проекте или системе. Они используются для сохранения и передачи информации о принятых решениях и обосновании их принятия.

1 Терминология

В «Надежность в процессах. Часть 1» [OpRes24-1] были определены (упрощены): надежность, процесс и надежность в процессах. Надежность – это способность безотказно работать (работать без отказов). Надежность процесса – это как способность безотказно работать («главное процесс»), так и выдавать требуемый результат («главное результат»). Количественно – это вероятность безотказной работы (вероятность застать процесс работоспособным) и вероятность требуемого результата на выходе процесса.

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

Это относится как ИТ-системе (кластер серверов) и не ИТ-системе (сейф), так и к системе процессов (операций) и составных частей процесса, включая его ресурсы.

Если в классической теории надёжности (Надёжность в технике [27.002]) обычно рассматриваются внутренние воздействующие деструктивные факторы на техническую систему типа отказ \ сбой оборудования \ ПО, то «Надежность в процессах и операциях» (операционная надёжность) рассматривает также непреднамеренные ошибки персонала (операционные риски) и внутреннее мошенничество, внешние атаки на процессы компании, клиентов компании (социальная инженерия), стихийные бедствия (техногенные катастрофы). В конечном счете неважно: «система процессов» отказала (не выполнила задачу) из-за какой-либо поломки или из-за ее перегрузки (от нежданного «наплыва клиентов» до DDoS-атаки), поэтому в состав показателей Надежность в процессах добавляем «доступность»:

В мире программирования создание собственных библиотек — это не просто возможность пополнения своего портфолио или способ структурировать код, а настоящий акт творческого самовыражения (и иногда велосипедостроения). Каждый разработчик иногда использовал в нескольких своих проектах однообразный код, который приходилось каждый раз перемещать. Да и хотя бы как упаковать свои идеи и знания в удобный и доступный формат, которым можно будет поделиться с сообществом.

Если вы ловили себя на мысли: ‭«А почему мне бы не создать свою полноценную библиотеку?‭», то я рекомендую прочитать вам мою статью.

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

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

Хочу поделиться своим опытом организации и построения корпоративной базы знаний для продуктовой ИТ-разработки. В конце статьи подведу итоги внедрения такой системы.

Прежде, чем объединяться, нам надо решительно размежеваться (Business continuity management vs Business Process Continuity vs Dependability in technics)

Синонимы: Надежность в процессах = надежность процессов = надежность операций = операционная надежность (с учетом синонимии словосочетаниями «сущ. + сущ.» [Морф23]).

En: dependability, reliability, resilience (availability, stability) Business Process. Непрерывность процессов — в контексте «business continuity» (Business Process Continuity, BPC) и т. п.

Хотелось бы немного осветить тему про ЛИМС на Хабре. В мире существует огромное множество лабораторий, которые занимаются измерениями, испытаниями, анализом каких-то объектов окружающей среды, продукции, биологических образцов и т.д.

Поговорим про внедрение ЛИМС в лаборатории.