Как стать автором
Обновить
82.18

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

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга
Уровень сложности

Экспорт из Yandex Wiki в Markdown. Не стали дожидаться и сделали сами

Уровень сложностиПростой
Время на прочтение2 мин
Количество просмотров572

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией.

В нашем чате и у пользователей регулярно встает вопрос переезда в Gramax c других платформ. Переезд с Confluence и Notion мы сделали прямо в интерфейсе приложения, а с Yandex Wiki — отдельной утилитой. Нет, мы не поленились, просто заметили, что сообщество Yandex Wiki такое давно просит: пример №1 (367 голосов), пример №2 (874 голоса).

В этой статье расскажем, как воспользоваться утилитой и выгрузить всю свою документацию из Yandex Wiki в обычный Markdown.

Поехали!

Новости

Что меня поразило в английском, когда я начала работать тех. писателем. Часть 2

Уровень сложностиСредний
Время на прочтение3 мин
Количество просмотров4.1K

Ну хорошо, не поразило. Но понравилось настолько, что я записала это в свой блокнот, а теперь, спустя 13 лет, делюсь с вами. Если вы работаете с документацией, интерфейсами или пишете ТЗ или bug reports, эти заметки будут вам полезны. Кстати, вот первая часть статьи — взгляните, если пропустили.

Читать далее

Diplodoc 5.0: как ускорить сборку документации в пять раз

Уровень сложностиСредний
Время на прочтение13 мин
Количество просмотров3.5K

Diplodoc — опенсорс‑платформа для работы с документацией в парадигме Docs as Code, которая создаётся в Яндексе силами команд Yandex Infrastructure и Yandex Cloud и является частью наших опенсорс‑инструментов. С её помощью мы собираем всю документацию компании. Это суммарно более 300 тысяч статей в более чем 2500 документационных проектов и порядка 6000 запусков Diplodoc CLI каждый день.

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

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

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

Читать далее

Читаем под одеялом с фонариком: темная тема и документация в ТМС TestY 2.1

Время на прочтение7 мин
Количество просмотров824

Привет, Хабр! Я Александр Зырянов, проектный менеджер TMS с открытым исходным кодом TestY. Сразу о главном: выложили в open source версию TestY 2.1. 

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

Какие еще изменения ждут пользователей в TestY 2.1 — читайте под катом.

Читать далее

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

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров2K

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

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

Откуда берётся эта эрозия программного обеспечения? Почему так выходит, что новые технологии не только не помогают, но иногда даже мешают нам писать качественные программы? Почему, когда мы стараемся делать хорошо — получается плохо?
И главное — что с этим делать?

Читать далее

Требования vs Реальность: Почему в ТЗ находят «дыры» и как это исправить

Уровень сложностиСредний
Время на прочтение12 мин
Количество просмотров3.2K

«А в ТЗ этого не было!» — знакомая ситуация?

Проблема, которая часто возникает: ТЗ составляются формально, без должной детализации — слишком абстрактно, без примеров или с пробелами в логике.

Читать далее

Как добавить теги в чат. Часть первая

Уровень сложностиПростой
Время на прочтение14 мин
Количество просмотров1.3K

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

Читать далее

Bash-шаблон на коленке: как выжить с языковой моделью без знаний кода

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров845

Хотел бы представить для обсуждения исходники проектов, в разработке которых использовался «ChatGPT (сервис OpenAI)» в качестве языковой модели.

Это история о том, как:

ИИ писал код;

ошибки становились уроками (learning by doing);

скрипт "на коленке" оброс структурой.

Особенность данного материала — в его спонтанности и полученных результатах, так как в процессе ChatGPT выступал то наставником, то «костылём», а где-то и источником новых проблем.

Что вы найдёте под катом:

краткий разбор архитектуры;

немного умозаключений о работе LLM.

Читать далее

Что меня поразило в английском, когда я начала работать тех. писателем. Часть 1

Уровень сложностиСредний
Время на прочтение4 мин
Количество просмотров11K

Вот так учишь-учишь английский, думаешь, что ты все знаешь и на коне, а потом приходишь в IT-компанию после ВУЗа и осознаёшь, что, по сути, не знала ничего.

Какие открытия я сделала для себя в английском, когда начала делать первые шаги в technical writing и переводах 13 лет назад? Я тогда тщательно фиксировала всё интересное - и делюсь этим списком с вами. Кстати, он будет полезен не только тех. писателям, но и тестировщикам, аналитикам и вообще всем, кто пишет ТЗ, отчёты и test cases.

Читать далее

Передача знаний: инструкция на случай ухода эксперта

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров4.6K

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

Читать далее

Use Case: как описывать эффективные сценарии использования. Part 2

Уровень сложностиСредний
Время на прочтение10 мин
Количество просмотров3.7K

Всем привет!

В этой статье — пошаговый разбор создания сценария использования (Use Case) на основе двух совершенно разных примеров: бронирование отеля в современном IT‑сервисе и покупка брюк на рынке 90-х.

Рассмотрим, как формируются эффективные сценарии использования от этапа создания Use Case диаграммы с помощью промта до детализации сценария.

Читать далее

Повышаем качество документации с помощью LLM

Уровень сложностиПростой
Время на прочтение9 мин
Количество просмотров4K

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

О Gramax мы писали ранее тут. В этой статье расскажу о Gramax Check — сервисе для автоматических проверок текста на базе LLM. По сути — нашей версии «Главреда», но с настраиваемыми правилами.

Интересно, давай!

ТЗ, за которое НЕ стыдно. Простые шаги к понятному техзаданию

Уровень сложностиСредний
Время на прочтение6 мин
Количество просмотров4.5K

«В мои прямые обязанности входит грамотное распределение ресурсов компании, а именно разработчиков 1С и аналитиков 1С в зависимости от их компетенций. Всё чаще в последнее время я слышу фразу: «Я никогда не видел качественное ТЗ». «Как так? Не видели? Давайте я вам покажу! Я пишу ТЗ, за которые не стыдно», — рассказывает моя коллега Татьяна.

Читать далее

Ближайшие события

«Давай покрасим холодильник в черный цвет»

Уровень сложностиСредний
Время на прочтение9 мин
Количество просмотров1K

При работе с BIM-моделями в формате IFC важно не только управлять геометрией и структурой здания, но и визуальными аспектами — например, цветами элементов. Цвет в IFC используется для улучшения читаемости моделей, визуализации этапов строительства, указания состояний (демонтаж, новое строительство и т.д.) или просто для улучшения презентации.

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

Читать далее

Почему нельзя слепо доверять даже официальным источникам: история от юриста по интеллектуальной собственности

Уровень сложностиПростой
Время на прочтение2 мин
Количество просмотров1.2K

Меня зовут Анна Лапа (Лапа - это моя реальная фамилия), я биотехнолог и юрист по образованию, патентный специалист по признанию. Занимаюсь патентами в сфере фармацевтики, медицины уже более 12 лет.

Эта неделя у Лапы прошла под лозунгом: «Не сотвори себе кумира» — даже если это Ведомство и самая официальная информация.

Почему? Расскажу на примерах:

Запрос на официальную почту в Ведомство

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

Базовые вещи — неожиданные ловушки

И тут ответ от Консультационного отдела меня удивил.

Читать далее

Как мы писали техдокументацию AsciiDoc нейронкой, экономя своё время и миллионы

Уровень сложностиСредний
Время на прочтение9 мин
Количество просмотров2.8K

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

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

Читать далее

Obsidian для профессионалов: рабочая система заметок на стыке подходов

Уровень сложностиСредний
Время на прочтение7 мин
Количество просмотров20K

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

Читать далее

От Docs as Code к Everything as Code: как Gramax меняет работу с документацией

Уровень сложностиСредний
Время на прочтение5 мин
Количество просмотров5.5K

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

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

Интересно, давай!

Арсенал бизнес-аналитика, или Топ-7 инструментов БА

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров6.9K

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

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

Читать далее

Системный аналитик и управление хаосом на проекте. Часть 2: Методика структурирования требований

Уровень сложностиСредний
Время на прочтение4 мин
Количество просмотров3.4K

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

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

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

Читать далее
1
23 ...