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

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

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

Как совместить порядок классической иерархии и гибкость Zettelkasten в одной базе знаний? Делюсь своим опытом построения эффективной системы заметок в Obsidian для инженеров и IT-специалистов: структура, шаблоны, метаданные, соответствие ITIL и ISO. Если вы хотите, чтобы ваши заметки работали на вас, а не против - эта статья поможет навести порядок и ускорить работу с документацией.

Привет, Хабр! Меня зовут Катя, я лидирую Gramax, open source-платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым.

В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code.

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

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

Диагностика хаоса - первый шаг. Но сама по себе она ничего не меняет. Это лишь осознание проблемы. Настоящая работа начинается на этапе структурирования требований.

Это тот момент, когда вы берёте множество разрозненных данных, противоречий, записей в Telegram, Excel-таблиц, каких-то старых писем и превращаете всё это в рабочий артефакт: чёткий, пригодный к реализации, контролируемый и понятный всем участникам.

Структурирование - это не про красивые документы. Это про построение системы управления требованиями, которая будет жить и развиваться вместе с продуктом. Именно здесь начинается настоящий системный анализ.

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

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

Короткий ответ — потому что чаще всего их невозможно читать.

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

Есть два типа системных аналитиков: те, кто на слова "Acceptance Criteria" кивают уверенно, и те, кто кивают с лицом человека, которому эти слова не приносит радости. А потом открываешь их спецификацию и понимаешь, что критерии приёмки там формулировал кто угодно, но только не человек, который собирается это реализовывать.

Если ты читал мою прошлую статью на Хабре про Gherkin, то уже знаешь, что синтаксис GWT - это не просто красивый способ писать тесты. Это способ фиксировать поведение системы в формате, который понятен и бизнесу, и тестированию и разработчику.

Про Gherkin слышали в основном те, кто связан с тестированием. Среди аналитиков он встречается крайне редко. Но если отбросить всё связанное с BDD и тестами, то Gherkin это формат описания поведения системы, где сценарий это обычный текст, написанный в структурированном виде “Given‑When‑Then”. Не код, не диаграмма, а короткое текстовое описание того, что происходит в системе в определённых условиях.

Не потому что модно, не потому что “так надо”, а потому что это удобно. Можно описать фактически всё: контекст, событие, результат - в трёх строках. Удивительно, что это не стало стандартом. Но как это работает на практике? Чтож… Щас выскажусь!

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

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

Привет, Хабр! Меня зовут Иван Арискин, я занимаюсь развитием продукта «Единый адрес» в HFLabs. Поскольку компания сравнительно небольшая, иногда приходится самостоятельно писать и редактировать Release Notes (RN). Они же — новости продуктов, или changelog. За одни меня благодарили, за другие — троллили, но я научился смещать баланс в сторону положительных реакций. 

В статье разберу, что и зачем писать в Release Notes и как заинтересовать бизнес техническими обновлениями. Пригодится всем, кто ведет документацию по продукту и хочет, чтобы она приносила реальную пользу. 

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

Пользовательский путь закладывается на этапе работы с требованиями. И, помимо UX/UI, важным этапом проработки является формирование сценариев использования системы. В этой статье разберем теоретическую часть и определим, что же такое Сценарий использования.

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

Статья будет полезна всем, кто хочет научиться проверять тексты в файлах любых форматов, будь то Markdown, YAML или комментарии в коде. Больше всего пользы из нее вынесут технические писатели и те, кто формирует процессы, связанные с документацией.

Помимо работы в командной строке, в статье рассматриваются примеры прекоммитных проверок и интеграции с VS Code.

Когда-то я относился к документации по-старому: написал – и забыл. Думаю, многие разработчики меня поймут. Традиционный подход зачастую сводится к тому, что документацию пишут в конце проекта или от случая к случаю, а затем она покрывается пылью. В эпоху Agile и DevOps такой подход не работает: изменения в коде происходят постоянно, и статичные тексты не успевают за ними. В результате документация стремительно устаревает, вводя команду в заблуждение и порождая ошибки​. Настала пора пересмотреть взгляд на эту часть разработки.

Хочу поделиться тремя подходами, которые кардинально изменили мой подход к документации. Это Continuous Documentation (непрерывная документация), MVD (Minimum Viable Documentation) – минимально жизнеспособная документация, и «документация как продукт». Каждый из них появился как ответ на боль, с которой мы сталкивались в гибкой разработке: как держать документацию актуальной, достаточной и полезной для пользователей. Расскажу о каждом по порядку – на примерах из собственного опыта, с живыми кейсами и свежими идеями. Возможно, эти подходы перевернут и ваше представление о том, какой должна быть документация в современных проектах.

Привет, Хабр! Это Екатерина Саяпина, Product Owner платформы МТС Exolve. Сегодня покажу, как быстро добавить виджет обратного звонка на страницу, созданную с помощью MkDocs — статического генератора сайтов с уклоном в техническую документацию. Такое размещение виджета бывает нужно в справочных разделах сложных продуктов, где клиентам может потребоваться консультация или разъяснение каких-то технических моментов.

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

Привет!

Меня зовут Алексей Фоменко. Я разработчик из Нижнего Новгорода.

Сегодня хочу рассказать вам о своем сервисе «Клюква».

«Развесистая клюква» или просто «Клюква» в общем виде означает ложные или искаженные представления о чем‑либо.

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

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

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

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

Всем привет! Меня зовут Севара Ахтямова и я работаю техническим писателем – аналитиком около 4 лет. В этой статье я расскажу, как AI помог мне справиться с рабочей рутиной — от генерации toctree до отладки сборки Sphinx-документации. Всё это — на реальных задачах. Я постаралась собрать побольше примеров из личного опыта. Надеюсь, не слишком много.

Привет, Хабр! Я Костя Макушев, работаю техническим писателем в подразделении ИТ-Инфраструктуры Т-Банка. В этой статье расскажу, какие проблемы возникли с пользовательской документацией наших продуктов и какие подходы мы начали применять, чтобы эти проблемы решить.

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

В этой статье я постараюсь рассказать и показать, почему я использую подход doc-as-a-code, как помогает git системному аналитику и зачем это всё.