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

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

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

Всем привет!

Меня зовут Татьяна и я старший технический писатель в компании 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. Встает вопрос, как автоматически строить матрацу по данным схемы процессов верхнего уровня.

Идея создания цифровых двойников прочно вошла в умы всех людей, занятых модернизацией производства во всем мире. О работе команды TechnologiCS в этом направлении мы уже говорили в статье «TechnologiCS 7.9 – цифровизация всего жизненного цикла продукции на базе одной системы». Теперь пришло время обсудить элементы инфраструктуры взаимодействия пользователей с цифровым двойником. Ведь автоматизировать сбор разнородных данных и собрать на них каркас цифрового двойника не является конечной целью в процессе создания модели производства – необходимо организовать работу сотрудников с огромным объемом все увеличивающейся информации. И не просто наладить работу, а сделать ее комфортной и эффективной. Для этого следует иметь в арсенале удобные точки взаимодействия с цифровым двойником, упрощающие работу и доставляющие необходимую информацию пользователю «just in time».

Здесь мы расскажем о таких инструментах в составе цифрового двойника TechnologiCS, как очки дополненной реальности, терминалы рабочих, мобильные точки доступа, Bluetooth-метки и сервисы визуальной аналитики.

Вариант автоматизированного формирования документа в формате *.docx с использованием скрипта на языке Python и библиотеки python-docx. Как правильно подготовить документ стандартными средствами Microsoft Office, что нужно учесть при создании скрипта, порядок сборки и сохранения документа.

Рассмотрим взаимодействие с компанией SweetCard, которая представляет достаточно удобную платформу таргетированных предложений держателям карт. В «МКБ Онлайн» это раздел «Персональные предложения».

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

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

За свою карьеру программиста я видел множество разных технологий и фреймворков от гигантов индустрии, таких как Oracle, Microsoft, IBM и т. п. Но в каждом из них было какое-то неудобство. А конкретнее у них у всех было одно общее, это необходимость реализовывать серверную логику чтобы можно было использовать ее в шаблонах. И это мне сильно не нравилось, приходилось делать одну и ту же работу из проекта в проект.

Один из таких подходов разнесения логики был паттерн программирования MVVM(Model-View-ViewModel). Его активно продвигали во фреймворках для C#. Структурно с точки зрения разнесения логики, я считаю этот паттерн самым удобным.

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