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

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

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

Всем привет! Вот уже несколько лет я занимаюсь построением процессов и внедрением ITSM-систем. В проектах внедрения систем у заказчика стремлюсь использовать принципы BDD (Behavior Driven Development) и DDD (Documentation Driven Development) и немножко KCS по причине собственной лени (двигатель прогресса!) и сильного нежелания заново возвращаться к «пройденному».

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

Вспомним наш любимый мультфильм «Падал прошлогодний снег» с его шикарными крылатыми фразами. Одна из них: «Уж послала, так послала». Вот и система так же — вместо отправки запроса посылает его куда-то далеко. А запросу обидно.

Всем привет!

Меня зовут Татьяна и я старший технический писатель в компании Orion Innovation. В нашей уже немаленькой команде мы используем довольно обширный стэк инструментов и технологий, но наиболее востребованы и удобны в работе - XML-редакторы с поддержкой DITA архитектуры. Моя статья - для технических писателей. Особенно для тех из нас, кто, как и я, имеет гуманитарное образование. Для разработчиков, особенно фронтендеров, это может показаться элементарными вещами, но для техписов, возможно, будет полезной. 

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

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

Платформы с предложениями о работе в IT-сфере, просто кишат вакансиями фронтенд разработчиков со сознанием React.

С одной стороны React нам дал возможность частями программировать интерфейс пользователя, разбирая его на части. А с другой стороны мы получили “молоток и гвозди” с помощью которых нам придется построить дом. И получилось так что сообщество программистов использует фреймворк React, чтобы написать свой фреймворк. И поэтому на рынке появляются новые фреймворки, основанные на React, которые уже решают конкретные задачи на реальных проектах. Одним из таких фреймворков является Next.js. 

Меня подтолкнула к написанию данной статьи, огромное количество статей и обучающих видео в интернет пространстве о возможностях Next.js. А конкретнее сказать, я начал разбираться в чем же всё-таки преимущество этого Next.js. И к моему удивлению, я понял, что MastermindCMS2, которую я успешно использую на множестве проектов, решает те же проблемы, что и пытались решить разработчики Next.js.

А вот что конкретно сделали разработчики Next.js мы рассмотрим и сравним в этой статье с технологией MastermindCMS2. Поехали!

Всем привет.

Многие из вас читали статью «Как создавать понятные логические (L3) схемы сети», после которой возникало непреодолимое желание задокументировать своё сетевое хозяйство. Два-три подхода, потом легко удавалось договориться с собой что изменения будут внесены в конце недели, месяца и т.д. По прошествии некоторого количества времени приходило понимание, что точечными изменениями уже не обойтись — надо так много двигать и компоновать, что проще всё сделать заново.

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

В первой статье я рассказал, как мы выбирали SSG для создания новой документации и как нам пришлось конвертировать DITA сначала в HTML, а потом в AsciiDoc.

В этой статье я расскажу, как я начал работать с SSG Antora, как я настраивал UI и добавлял сквозной поиск по сайту.

Как их только не называют: техписы, техрайтеры, документаторы... Хорошо, хоть не архивариусы!

Спрос на хорошую, качественную документацию к программам и системам постоянно растёт. При этом сейчас на рынке наблюдается серьёзный дефицит профессиональных технических писателей. Опытные технические писатели сейчас буквально на вес золота. Во всём мире профессия technical writer (или technical author) считается престижной и перспективной. Техническое документирование — это одна из замечательных пограничных областей для тех, кто так и не смог смириться в школе с разделением на гуманитариев и математиков.

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

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

Для справки:

HLD (high-level design) – верхнеуровневое описание архитектуры системы, где представлены основные компоненты и их взаимодействия. 

LLD (low-level design) – низкоуровневое детальное описание каждого из компонентов системы.

Привет, Хабр! Я Катя из команды техписателей в Ozon. Мы продолжаем расти и развиваться, поэтому вслед за статьёй о видах документации хочу разобрать, какие проблемы внутри команды можно документацией решить.

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

Мы в Юле применяем подходы и паттерны, которые позволяют нам избегать проблем, связанных с интеграциями: создаем абстракции, где размещаем транспортный протокол и логирование, используем circuit breaker, обращаемся к асинхронным подходам, используя Kafka как шину данных. Предлагаем погрузиться на несколько слоев абстракции и вместе решить любые проблемы интеграций: от тайм-аута до кэширования.

Привет всем читающим! Меня зовут Владимир, я - технический писатель в компании Docsvision. Я создаю документацию для нашей «Платформы по управлению процессами и данными для крупного бизнеса и госкомпаний». Это как СЭД, только лучше (C).

Я хочу поделиться историей о том, как мы пришли к новой документации и почему. Сначала я кратко расскажу, как устроена наша "старая" документация, а потом расскажу о том, как мы пришли к новой документации.

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

Эпопея с автодокументацией началась у нас неспроста: 300 разработчиков, 500 репозиториев и 400 сервисов — все живет на 600 хостах и использует 600 баз данных. Изменения происходят настолько часто, что ручной поиск данных в наших масштабах — та еще морока. При этом раньше никакого общего хранилища с актуальной информацией о владельцах проектов, о конфигурациях хостов и связанных с проектами сервисах не было. Расскажу, как мы вконец устали от квестов, перешли на сторону автодоки и почему выбрали в помощь Insight.

Меня зовут Юля, я руковожу командой SRE. Помимо стабильности сервисов, моя команда занимается поддержкой инструмента, который нам позволяет за этими сервисами следить. Это отдельное приложение, генерирующее документацию по всей нашей инфраструктуре.

В 2018 году, когда я только пришла в компанию в роли девопса, мне дали для погружения в процессы простую задачу: допилить скрипт локального разворачивания проектов, чтобы он корректно работал под macOS. То есть скрипт уже был, он успешно работал для Linux-окружения. Его нужно было просто адаптировать, подправить пару регулярок, настроить сеть, дописать инструкцию — совсем не сложно. Я довольно быстро сделала правку в самом инструменте, и казалось, что нет никаких проблем. Но дальше 15-минутная на первый взгляд задача растянулась на 3 месяца.

На написание этой статьи меня подтолкнула мысль о том, что все малочисленные конструкторские бюро (1...4 конструктора), с которыми я имел дело или в которых работал, имеют крайне низкую эффективность. Сами же сотрудники таких микро КБ как правило живут "с бревном в глазу".

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