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

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

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

Документацию мы ведем в Confluence — и обычно, когда я рассказываю про Confluence, у многих он вызывает, мягко говоря, неприятные ассоциации. Миллион разделов, неудобная навигация, портянки бесконечного текста и многое другое, что отбивает желание даже открывать любую wiki. Но я спешу вас обрадовать — все может быть совсем иначе!

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

Всем привет! Меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT более 10 лет.

Поговорим о структуре Технического задания.

Резюме.
В статье дается ссылка на файл в формате ODT (основной формат файлов, используемый в текстовом редакторе LibreOffice Writer), содержащий макросы на «родном» для LibreOffice языке программирования макросов BASIC, которые осуществляют экспорт текста из LibreOffice Writer в новый файл в формате Habr Flavored Markdown (далее - HFM) или HTML, в виде, пригодном для размещения статьи в интернете, например, на сайте habr.com.

Текст данной статьи был экспортирован в формат HFM для размещения на сайте habr.com с помощью библиотеки макросов, содержащихся в данном файле.

Для использования достаточно скачать указанный файл (его можно переименовать), заменить в нем текст на свой текст, подготовленный в соответствии с описанием в статье, и вызвать макрос. В папке со скачанным файлом появится новый файл в выбранном формате.

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

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

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

Бизнес хочет простых вещей: простого и быстрого масштабирования, гибкости для адаптации решения, и чтобы всё было просто для клиента.

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

• надежность и доступность сервисов банка;

• прозрачность информационного ландшафта для аудита;

• повышенные требования к финансовой и информационной безопасности;

• соответствие требованиям к ИТ инфраструктуре со стороны ЦБ РФ.

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

У этой статьи два автора: Борис Пишванов — начальник управления Solution архитектуры и Михаил Салахов — архитектор направления Альфа-Банка. Мы расскажем, что делаем, чтобы архитектурный ландшафт Альфа-Банка стал прозрачным и простым для понимания огромного количества заинтересованных лиц. Обратите внимание на статью, если думали над тем как, систематизировать и упорядочить архитектуру большого предприятия.

Всем привет! Меня зовут Екатерина Мишинёва, я ведущий технический писатель с опытом работы в IT-компаниях более 10 лет.

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

Привет, Хабр! На связи снова Юрий Никулин. В первой части статьи я рассказывал, почему в Cloud.ru решили перейти на doc as code и какой технологический стек мы выбрали. В этой части поделюсь самим процессом — расскажу, как настраивали, тестировали и внедряли новую систему и что из этого вышло.

Всем привет! Меня зовут Екатерина Мишинёва, я ведущий технический писатель с опытом работы в IT-компаниях более 10 лет.

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

Это первая статья в корпоративном блоге компании documentat.io. Мы занимаемся заказной разработкой технической документации и помогаем компаниям настраивать процессы документирования.

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

Как структурировать документацию так, чтобы писать её стало проще?

Для технических средств ОТБ по постановлению Правительства РФ № 969 от 2016 года, требуется сертификация. Клиент производит стационарные арочные металлодетекторы. В статье мы расскажем:

• почему клиент сомневался в возможности пройти сертификацию;

• почему продукция могла уехать на Дальний Восток;

• от чего зависит орган, который отвечает за сертификацию.

Всем привет, меня зовут Женя Колесников, я из команды Yandex Infrastructure. Сегодня я расскажу, как мы пришли к написанию документации в концепции Docs as Code, придумали для этого набор инструментов, назвали его красивым именем Diplodoc и выложили в опенсорс — теперь вы тоже можете им воспользоваться.

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

Всем привет! Меня зовут Владислав Москалёнок, и я работаю техническим переводчиком и редактором в сфере телекома и IT уже более 20 лет. Сегодня хочу поделиться опытом команды Bercut в цифровизации переводческих процессов. Из статьи вы узнаете, как мы реализовали комплексное решение, где сочетается технология накапливаемой памяти (TM) и нейронного машинного перевода (NMT). Если вы технический переводчик или вам просто интересна тема  локализации ПО —

Привет! Меня зовут Рафаэль Туляков, я руковожу направлением кадрового документооборота в компании, которая внедряет сервисы для бизнеса: облачные кассы, инструменты для бухгалтеров, автоматизацию учёта. 

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

Обзорная статья о QPR Enterprise Architect. Основные возможности и преимущества данного инструмента.

Л - Добрый день, дорогие зрители, сегодня мы продолжаем нашу серию репортажей «Стартаперы Кварцевой Лощины». С вами снова я, независимый журналист, Лайер Бала-Больё, и сегодня наш гость - талантливый селфмейд, добившийся всего сам, 19-летний сын известного миллиардера, стартапер Жу̒лико Бары̒гги младший.

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

Жулико, вы только что были спикером на проходящем в Сан-Дьябло Блаблатоне и упомянули такую интересную вещь, как ШвабрОпс - можете рассказать нашим зрителям, что это такое и с чем его едят.

Ж – Привет, Лайер, привет всем. Да, на Блаблатоне я рассказывал про ШвабрОпс – это новое перспективное направление в IT. Дело было так. Я маялс…т.е. интенсивно работал в офисе и обратил внимание, что какой-то очкастый толстый задрот ходит туда-сюда из кабинета в кабинет. Я спросил секретаршу – кто это такой? Она ответила – это наш ДевОпс.

Л – Ага.

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

Л – Угу.

Ж – Ну и все, собственно. Я подумал-подумал и решил – а зачем нам уборщица?! Пусть этот дев…как его там…в общем – пусть он еще и пол протирает параллельно. Это же какая экономия получается!  

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

О будущем системных аналитиков, о ChatGPT и LLM, что не заменит аналитиков, слишком большом списке требований, что добавить в резюме, low-code/zero-code системах, стажировках и ветках прокачки, поговорили с Алексеем Лобзовым, руководителем направления развития компетенции системного анализа в Альфа-Банке.

Всем, привет! Меня зовут Алёна Барыкина и я методолог отдела информационного моделирования департамента цифровизации инвестиционно-строительных проектов компании "Bimeister". И сегодня, хочу с вами поделиться важным аспектом исполнения желаний в проектной деятельности с использованием цифрового информационного моделирования

Вы, конечно же, знаете ключевой принцип успеха любого проекта, включая создания цифровой информационной модели (ЦИМ) - «Начинай только тогда, когда результат уже в уме». Выражение, которое отражает саму суть любой проектной деятельности.

Только вот вопрос - а что каждый участник процесса понимает под необходимым результатом в проекте создания цифровой информационной модели?

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

Когда Заказчик говорит, что ему нужна цифровая информационная модель, он говорит не просто о модели, а о преимуществах, которые он хочет получить с помощью ЦИМ: