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

"Если не говорить о желаемом - оно может так и не стать действительным". В. Синявский.

14 февраля 2022 года GitHub объявила о старте нативной поддержки диаграмм Mermaid.js в README-файлах GitHub. Нововведение помогло быстрее и эффективнее оформлять блок-схемы и графики для документации. До этого диаграммы вставлялись в виде изображений и если содержимое менялось, то надо было сначала нарисовать новое изображение, а потом вставлять его. Сейчас же можно просто исправить несколько строк в коде и система сгенерирует новый график.

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

Сегодня хочу поделиться с вами своим опытом по использованию тех или иных инструментов в своей работе.

В данной статье собраны основные операции и алгоритмы работы, позволяющие повысить эффективность разработки документации в редакторе Microsoft Word как индивидуально, так и при командной работе.

Не рассматриваются подходы с использованием Markdown, Pandoc, Asciidoc и Confluence как более сложные и узкоспециализированные, а статью хотелось сделать доступной и понятной не только молодым людям, но и людям старших возрастов.

Привет, Хабр! Меня зовут Богданова Софья, я технический писатель в компании Documentat, где мы занимаемся разработкой технической документации для различных IT-проектов.

За все время работы приходилось сталкиваться с кучей разной документации, но сейчас я плотно засела с документированием по ГОСТу. Собственно, о чем и будет этот пост.

При выполнении проектов, в которых требуется разработка конструкторской документации соответствующей ГОСТам ЕСКД или СПДС, возникает много задач, связанных с ее корректным изготовлением. Часть этих задач связана с непосредственным оформлением документов – заполнением основных надписей, полей в форматных рамках документа. Другая часть задач связана с поддержанием связности информации в пределах комплекта документов -  единство используемых децимальных номеров, названий изделий, используемых в тексте наименований и тому подобных вещей. Такие задачи можно решать по разному, но автоматизация, безусловно, облегчит жизнь разработчику.

В данной статье, я расскажу о своем подходе к автоматизации такой работы на примере документов Word. Этот же подход применим и к Visio и к AutoCAD и к любому продукту, в котором предусмотрена возможность использования Visual Basic for Application (VBA).

Представим себе такие входные условия для решения:

в составе документации должны быть документы по ГОСТ 2.102, в том числе текстовые, оформленные с учетом ГОСТ 2.105, схемы по ГОСТ 2.701 и, не дай бог, что-то еще строительное по ГОСТ 21.101. А из инструментов есть только стандартный Microsoft Office, Microsoft Visio, Autodesk AutoCAD (это если бог был немилостив) и собственное желание оформить все как можно быстрее, лучше и не затрачивая усилий (то есть, в наличии имеется продуктивная лень).

Свободного времени становится всё меньше и меньше, поэтому в этот раз перейду сразу к делу.

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

Лучше поздно чем никогда, поэтому сегодня мы:

• починим связку ShowHide macro и аннотаций на странице;
• пофиксим проблемы с поиском;
• поменяем шаблон для страницы входа;
• сделаем оглавление страницы в боковой панели;
• установим пакеты, которые не находятся обычным поиском и отобразим Swagger на странице.

Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io, помогая российским IT-компаниям создавать качественную документацию.

Мы пишем документацию с нуля (руководства пользователя, справочники API, архитектурную документацию) и поддерживаем уже имеющуюся и проводим консультации по настройке документационных процессов. И почти каждый запрос от наших клиентов начинается с признания: «Кажется, с нашей документацией что-то не так».

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

1) Документация полностью отсутствует.
2) Документацию неохотно пишут.
3) Документацию неохотно читают.
4) Документация есть, ее пишут и читают, но она кажется бесполезной.

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

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

Всем привет! Меня зовут Женя, я менеджер по развитию продукта в компании «Диджитал Дизайн».

Все знают, что ничего в этом мире не делается просто так. У всего есть причина – в мире IT эта причина называется «болью». Обычно наши заказчики приходят к нам с чётким пониманием своей проблемы и предполагаемых путей её решения. Однако, иногда случается так, что приходится работать с очень размытыми требованиями к потенциальному проекту.

Что делать в таких случаях? Сегодня я поделюсь некоторыми подходами, которые активно использую в своей практике.

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

По какому-то странному стечению обстоятельств в русской раскладке отсутствуют даже такие символы, как больше/меньше или фигурные скобки (хорошо, что хоть плюс с минусом не забыли). И приходиться переключаться для их набора.

Решено было избавиться от этой проблемы.

«Мои письма никто не читает.»

«Я уже всё всем написал, а коллеги продолжают спрашивать одно и то же. Бесит.»

И особенно популярное: «Мы ещё неделю назад написали, что удалим эту таблицу из базы, и сказали адаптировать код! Так что мы не виноваты, что сайт (пайплайн, приложение, <подставь своё>) упали.»

Начну с весьма непопулярного заявления: ответственность за доставку и восприятие сообщения процентов на семьдесят лежит на отправителе (то есть на тебе). Конечно, если твой коллега — заядлый социопат и в принципе не читает никакие письма, наука здесь бессильна (но и тут есть варианты, которые обсудим ниже). Однако чаще бывает, что коллеги в принципе готовы потреблять наши сообщения, но безудержные приступы зевоты и недоумения делают своё чёрное дело.

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

(Ещё одним приятным следствием из умения писать качественные письма стало повышение доверия к нашей команде, которое мы измеряем, регулярно опрашивая наших бизнес-партнёров. Простая и понятная коммуникация — признак заботы о собеседнике.)

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

Цель: смоделировать и изготовить низкополигональную собаку. Материал - сталь конструкционная.

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

В конце статьи вас будут ждать фотографии процесса изготовления и готового изделия.

Привет, Хабр! Меня зовут Алиса Комиссарова, я менеджер проектов в департаменте информационной поддержки Positive Technologies.

Еще пять лет назад технические писатели Positive Technologies для создания руководств пользователя и прочей техдокументации использовали разные программы, произвольно затачивая стиль и оформление документов под свои проекты. В один прекрасный день объем разрабатываемой документации перестал поспевать за бурным ростом бизнеса и запросами наших подразделений, и мы поняли, что надо срочно что-то делать. И тогда к нам пришла она — идея корпоративного управления контентом.

В этом посте я поделюсь историей о том, как мы в Positive Technologies внедряли (ох, это было непросто) систему SСHEMA ST4, профессиональную CMS для создания и управления информацией о продуктах, в рабочие процессы различных департаментов, а также расскажу:

•      быстро ли прижилась система в компании,

•     сколько сотрудников сейчас ею пользуются,

•     как мы продолжаем внедрять СМS в различные департаменты,

•     какие у нас планы на будущее.

В этой статье я дам краткую вводную, что такое Archi и ArchiMate. Расскажу о коллективной работе с Archi используя расширение coArchi, после чего предоставлю контейнер позволяющий автоматизировать работу по созданию HTML и PDF документов с ArchiMate моделями. Завершим же, созданием своего GitHub Action, настроим GitHub и GitLab пайплайн с последующей публикацией модели в GitHub/GitLab Pages.

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

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

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