Как стать автором
Обновить
2.68
Рейтинг

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

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга

Удачный шаблон документации на API, который будут читать

Анализ и проектирование систем *Подготовка технической документации *

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

Вы бы стали читать рецепт из 10 страниц, чтобы приготовить салат? Что-то я сомневаюсь. Схожая ситуация бывает в документации, когда она пишется без шаблона по принципу "чем больше, тем лучше".

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

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

Читать далее
Всего голосов 1: ↑1 и ↓0 +1
Просмотры 6.3K
Комментарии 5

Новости

«Атака клонов» или пишем макрос для клонирования репозитория GitLab внутрь XWiki

Программирование *Groovy & Grails *Git *Подготовка технической документации *
Tutorial

Наконец-то я "раздобыл" немного свободного времени, а значит пришла пора продолжить серию туториалов по XWiki.

После публикации одной из моих статей MaxK82 спросил у меня, можно ли как-то в XWiki подключить документацию из git репозитория, так чтобы наладить её версионирование. К сожалению эта статья не ответит на его вопрос, но возможно укажет направление, в котором стоит "копать".

Поэтому сегодня мы с вами:

- создадим простенький, но зато свой макрос в XWiki;

- клонируем прямо в XWiki репозиторий с GitLab;

- отобразим Readme.md из репозитория внутри страницы XWiki.

Читать далее
Всего голосов 3: ↑3 и ↓0 +3
Просмотры 666
Комментарии 0

Зачем оформлять документы о создании программного обеспечения (мнение практикующего юриста)

Разработка мобильных приложений *Разработка игр *Разработка робототехники *Дизайн Подготовка технической документации *
Из песочницы

Согласно данным опроса сервиса SuperJob, в 51% опрошенных компаний есть сотрудники "на удаленке". При чем, чаще всего на дистанционную работу переводят сотрудников из сферы информационных технологий.

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

Состав документов может варьироваться от количества задействованных в разработке лиц (особенно если речь идет об авторских коллективах, крупных контрактах с длинными «цепочками» заказчиков, подрядчиков, субподрядчиков и т.д.).

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

Читать далее
Всего голосов 3: ↑3 и ↓0 +3
Просмотры 2.4K
Комментарии 25

Моделирование угроз (описание объекта защиты)

Информационная безопасность *Подготовка технической документации *

В феврале на ТБ-Форуме 2022 ФСТЭК в лице Гефнер И.С. представил доклад на тему «Практика реализации методики оценки угроз безопасности информации (УБИ)» (далее – Доклад), посвященный разработке модели угроз (МУ) в соответствии с методическим документом, утвержденным 05.02.2021 (далее – Методика). В частности, было сказано о том, что 67% присылаемых на проверку МУ возвращаются на доработку. Разработанная мной МУ оказалась в списке оставшихся 33%. В связи с эти решил поделиться своим видением процесса моделирования угроз.

В Приложении 3 Методики приведена рекомендуемая структура МУ, которой стоит придерживаться. Раздел «Общие положение» пропустим и рассмотрим раздел «Описание систем и сетей и их характеристика, как объектов защиты». Далее будем пользоваться понятием «Объект защиты» (ОЗ), включающим в себя все компоненты защищаемой системы и/или сети. Прямых замечаний у регулятора к этому разделу не было, но некоторые замечания к другим разделам прямо связаны с качественным описанием ОЗ.

Целью данного раздела является описание ОЗ, позволяющее определять возможные негативные последствия, объекты воздействия, источники УБИ (модель нарушителя), способы реализации (возникновения) УБИ, и выполнить построение сценариев реализации УБИ. Кому интересно, прошу под кат.

Читать далее
Всего голосов 3: ↑2 и ↓1 +1
Просмотры 1.9K
Комментарии 10

С чего начинается разработка программного обеспечения?

Управление разработкой *Подготовка технической документации *

Это может быть листок бумаги исписанный разными почерками и с пятном от кофе в уголке, а может быть строгий документ в соответствие с ГОСТ «34.602-2020», подразумевающий подготовку документации в соответствие с ГОСТ «Р 59795-2021», включая программу и методику испытаний. Мы понимаем что тратить много времени, сил, а зачастую и денег на подготовку объемной документации мало кто хочет, поэтому подготовили облегчённый подход к разработке технического задания, в нём нет ничего нового, скорее тот минимум который поможет прозрачно донести требования до исполнителя.

Читать далее
Всего голосов 15: ↑1 и ↓14 -13
Просмотры 3.7K
Комментарии 21

О нормах и законах или Как вылечить процесс техдокументирования (спойлер: это больно)

Блог компании Цифра Управление разработкой *Разработка для интернета вещей *Интернет вещей Подготовка технической документации *

Привет, Хабр! Ранее я писал о том, как можно подружить разработчика и писателя в рамках единого процесса и о подходе Docs-as-code к документированию разработки. Здесь мне бы хотелось поразмышлять, как в условиях agile и постоянного развития одновременно перестраивать документирование под требования других процессов, зачастую не очень предсказуемых, и при этом сохранить максимальную целостность, качество и единообразие документации.

Читать далее
Всего голосов 6: ↑6 и ↓0 +6
Просмотры 1.6K
Комментарии 0

Plantuml в работе системного аналитика. Пиши uml диаграммы текстом, чтобы сэкономить время

Анализ и проектирование систем *Подготовка технической документации *

Раньше я использовала для рисования диаграмм плагин в Confluence drawio или Microsoft Visio, который позволяет в графическом виде нарисовать диаграммы. Основная боль (для меня) у этих инструментов заключалась в том, чтобы поправить множество диаграмм надо открывать каждую, двигать элементы, стрелочки. А это время.

Изучив возможные решения я пришла к plantuml. Это инструмент, который позволяет с помощью текста рисовать диаграммы. Его можно использовать через макрос в Confluence или плагин в Idea, что позволяет за раз править много диаграмм, так как это текст. Не верите? Давайте попробуем на примере.

Читать далее
Всего голосов 9: ↑8 и ↓1 +7
Просмотры 4.3K
Комментарии 17

Как задавать требования к качеству ПО в цифрах?

Тестирование IT-систем *Анализ и проектирование систем *Подготовка технической документации *

Требования к качеству, несмотря на свой небольшой размер, очень сильно влияют на реализуемость всей совокупности требований, на трудоёмкость, длительность и стоимость реализации, а следовательно окупаемость инвестиций в разработку и в целом возможную успешность проекта.

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

Но в мире честных, открытых отношений выгоднее заранее обсудить эти аспекты, чем потом с удивлением спорить при сдаче, что система тормозит, в ТЗ про это ничего не сказано, «вы же профессионалы» и всё такое.

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

При этом остаётся прагматический вопрос — а что именно писать в требования, чтобы они были полезными, измеримыми, реализуемыми?

С точки зрения системной инженерии, требования к качеству программной системы являются разновидностью системных ограничений (constraints) и в этом они отличаются от требований к способностям (capabilities) системы, в мире ИТ обычно называемых «функциональными».

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

Давайте попробуем сделать это хотя бы ремеслом.

Читать далее
Всего голосов 12: ↑12 и ↓0 +12
Просмотры 7.5K
Комментарии 2

Bpmn для системного аналитика. Освойте нотацию за 1 час

Анализ и проектирование систем *Подготовка технической документации *

Зачем придумали нотации (прим. система условных обозначений, принятая в какой-либо области)? Все просто, они помогают предотвратить много споров и конфликтов между людьми. Давайте посмотрим как BPMN (прим. Business Proccess Modeling Notation) нотация помогла нашим героям.

В некотором царстве, в некотором государстве жил был Царь и была у него мечта создать онлайн школу для обучения своих подданных. Созвал царь ученых со всего мира думу думать и решение предлагать. Три дня и три ночи трудились лучшие умы мира над решением задачи и вот предложили свое решение царю. И вот беда, Царь не понимает решений, один на иностранном языке все описал, другой непонятными символами. И говорит Царь: "Нет, братцы, так дело не пойдет, давайте-ка вы на одном языке мне все нарисуете, тогда я смогу выбрать лучшее решение!"

Царь предложил систему условных обозначений (нотацию bpmn) и обучил ученых как ей пользоваться.

Читать далее
Всего голосов 8: ↑4 и ↓4 0
Просмотры 5.8K
Комментарии 47

В поисках минимального ТЗ

CRM-системы *Управление проектами *Подготовка технической документации *

В этой статье я поделюсь своим опытом как я смог вывести формулу минимального написания документации для успешного процесса разработки. Я руководил несколькими проектами, где использовали ТЗ от макета в пейнте до ГОСТ 34, и могу сказать, что документация — это всегда баланс между муторной описательной работой и шансом успешно довести проект до релиза. Писать документацию очень не хочется, а если ты еще ленивый и знаешь, что в 50% случаев ее вообще никогда не будут читать, то ощущение сизифова труда вводит в уныние.

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

Читать далее
Всего голосов 10: ↑10 и ↓0 +10
Просмотры 6.8K
Комментарии 9

Почему пользователи не читают документацию или как можно улучшить руководство пользователя 2

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

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

Продолжение статьи, рассказывающей, возможно, очевидные вещи по созданию технической документации.

Первая часть - https://habr.com/ru/post/654411/

Читать далее
Всего голосов 3: ↑2 и ↓1 +1
Просмотры 1.7K
Комментарии 4

Сравнение возможностей AsciiDoc и DITA

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

Всем лучи добра! Меня зовут Владимир Маркиев, я -- технический писатель в Docsvision. Расскажу вам о двух Docs as Code инструментах. На случай, если вы делали документацию в ворде или ещё где-то, а теперь решили отделить форматирование от документации и захотели "чтобы было чисто!". Побуду сегодня вашим Мистером Пропером.

Читать далее
Всего голосов 6: ↑6 и ↓0 +6
Просмотры 2K
Комментарии 13

Рабочий шаблон архитектурного решения

Блог компании БКС Мир Инвестиций Анализ и проектирование систем *Подготовка технической документации *

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

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

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

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

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

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

Дальше, пожалуйста
Всего голосов 13: ↑13 и ↓0 +13
Просмотры 8.7K
Комментарии 29

Пять критериев неэффективной базы знаний и как всё исправить

Блог компании Конференции Олега Бунина (Онтико) Управление разработкой *Управление проектами *Учебный процесс в IT Подготовка технической документации *

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

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

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

Читать далее
Всего голосов 13: ↑13 и ↓0 +13
Просмотры 4.3K
Комментарии 3

Автоматизация разработки конструкторской документации средствами VBA. Продолжение

Блог компании Специальный Технологический Центр Visual Basic for Applications *Подготовка технической документации *

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

Читать далее
Всего голосов 2: ↑2 и ↓0 +2
Просмотры 2.8K
Комментарии 3

Почему пользователи не читают документацию или как можно улучшить руководство пользователя

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

Часть первая

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

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

Читать далее
Всего голосов 10: ↑9 и ↓1 +8
Просмотры 5.9K
Комментарии 18

Все начинается с брифа

Разработка веб-сайтов *Подготовка технической документации *
Из песочницы

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

Читать далее
Всего голосов 3: ↑3 и ↓0 +3
Просмотры 1.6K
Комментарии 5

Рисуем диаграммы Mermaid.js в README-файлах GitHub

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

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

Читать далее
Всего голосов 43: ↑43 и ↓0 +43
Просмотры 6.5K
Комментарии 8

Набор инструментов для работы Системного аналитика

Анализ и проектирование систем *Подготовка технической документации *
Из песочницы

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

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

Читать далее
Всего голосов 10: ↑6 и ↓4 +2
Просмотры 6.3K
Комментарии 7

Повышаем эффективность работы с Word

Разработка для Office 365 *Копирайт Софт Подготовка технической документации *

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

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

Читать далее
Всего голосов 13: ↑12 и ↓1 +11
Просмотры 11K
Комментарии 19

Вклад авторов