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

Уже три года, как мы постепенно передаем солюшн-архитектуру в команды разработки. Приходится часто объяснять, как сделать архитектурное решение коллегам, которые раньше подобными вещами не занимались. Отсюда родилась идея этой статьи – поделиться опытом, который сложился у меня и моих коллег за 10 лет практики. Важная часть этого опыта – шаблон архитектурного решения с пояснениями как его заполнять и почему именно так. По сути, шаблон - это структура необходимых знаний. Если вы нашли ответы на все вопросы шаблона, значит вы продуманно подошли к созданию архитектуры. А еще, сделали хороший документ, с которым удобно работать.

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

Статья будет полезна:

• Аналитикам, тимлидам, программистам, которые уже делают или собираются делать архитектурные решения;

• Архитекторам, чтобы улучшить качество выпускаемых документов;

• Главным архитекторам с целью посмотреть «а как там у них».

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

Меня зовут Анжелика Федько, я успела поработать с базой знаний с разных сторон. Например, пока была инженером технической поддержки, занималась её наполнением, созданием новых статей и актуализацией. Когда стала тимлидом, взяла на себя уже более стратегические проекты, которые нацелены не на улучшение конкретной статьи, а на базу знаний в целом. Таким образом, за 6 лет работы с базой знаний я успела рассмотреть ее с разных сторон.

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

Продолжение статьи об автоматизации создания комплектов проектных документов по ЕСКД и СПДС.

Часть первая

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

Приятного чтения

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

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.