Всё о деятельности технических писателей
Как эффективно организовать процесс обмена знаниями в компании, минимизировать потерю времени и повысить продуктивность команды. В статье делимся проверенными инструментами и подходами из личного опыта техписов, которые сделали взаимодействие внутри команды удобным и результативным.
С вами Семён Факторович и компания documentat.io. Продолжаю делиться результатами большого соцопроса среди техписателей, который мы проводили в начале 2024 года.
В этой части поговорим об инструментарии: какой самый распространённый инструмент ведения документации в России? Получилось ли импортозаместить Confluence? Что популярнее — Markdown или Asciidoc? Сколько российских техписателей работают в парадигме Docs as Code?
«Возьми вишневый мамин плащ и кружку молока» – вспомнился мне фрагмент моего любимого стиха из книги Григория Остера «Вредные советы». И я понял, что у меня для вас тоже есть пара советов. Конечно, мои советы не такие «сочные», но все же использовать их стоит с умом и большой осмотрительностью.
Мы рассмотрим три приема работы с XWiki, которые скорее всего выбиваются из хорошей практики, но могут быть полезны в ваших экспериментах. В любом случае, если вы пересели с иглы Confluence на его open source аналог (со слов разработчиков). То вам, точно не помешает знать о возможностях доработки его напильником.
Начнем мы с получения доступа к командной оболочке прямо из XWiki, а закончим обхождением ограничений CORS с помощью скрипта на Python.
Как говорится: «Милости прошу под кат»
Запутались в выборе платформы для работы с документацией? Функций море, терминология запутанная, а вариантов столько, что глаза разбегаются—даже опытные специалисты порой теряются! Мы собрали для вас 10 ключевых критериев, которые помогут найти идеальную систему управления документацией без лишней головной боли. Давайте разберёмся вместе!
Когда говорят о требованиях, первое, что приходит в голову: «О, опять список хотелок!» На самом деле, это запросы, идеи и проблемы, которые стейкхолдеры (то есть все те, кого заденет ваш проект) выдают разработчикам, аналитикам и менеджерам. Это может быть как организация в целом, так и один несчастный человек: от директора до сотрудника, который просто хочет, чтобы его жизнь стала немного проще.
Например, директор хочет знать, чем занимались его сотрудники в месяц. Менеджеры хотят, чтобы у них был инструмент контроля, а пользователи хотят, чтобы этот инструмент не превратил их жизнь в бюрократический кошмар.
В этой статье я хочу рассказать о том, как в нашей команде появился 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 покрывают все потребности любого проекта. В том числе за счет возможности расширения своими библиотеками.
Привет! Меня зовут Максим Соколов, я — аналитик в команде “Управление доступностью товаров и категорий”. В нашей команде была выделена отдельная подгруппа, которая создавалась специально под новый продукт-фичу для селлеров. Сразу стало понятно, что для реализации нового функционала требуется разработка нового микросервиса. Командой разработки было принято решение интегрироваться по 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. А где продукты, там и документация. С одной стороны, её ведение — вопрос явно не первостепенный. А с другой — неактуальная информация не только бесит печалит, но и влечёт за собой дополнительные траты.
Не спешите кидаться тапками, если тема кажется слишком очевидной. Иногда чужой пример — лучший стимул взять и наконец сделать это у себя.
Наш путь по приведению в порядок накопившейся документации можно разделить на две части. Сначала мы прошлись по ней в ручном режиме, потом запустили автодокументацию. Я расскажу, что и зачем мы делали вручную, поскольку без этой части работы автоматизацию запускать смысла нет. Во второй части статьи будет непосредственно про автодоку.