Все потоки
Поиск
Написать публикацию
Обновить
36.21

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

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

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

BPMN не в теории, а на практике

Время на прочтение7 мин
Количество просмотров39K

Или ментальные «ловушки», которые мешают аналитикам использовать нотации.

От системного аналитика требуют знание нотации BPMN (Business Process Model and Notation). Недавно среди своих коллег — системных аналитиков — я провела опрос о BPMN. Мне было интересно узнать используют ли мои коллеги нотацию, как именно и в чём сложности. В результате я нашла парадокс: большинство коллег считают, что нотации необходимы в работе, но на практике используют меньше половины. Почему возник такой парадокс и как его решить?

Попробую разобраться

«Нам он и нафиг не нужон, технический писатель ваш!» (с) или для чего он вам всё-таки нужен

Время на прочтение8 мин
Количество просмотров6.5K

Прекрасные дамы и неподражаемые господа, здравствуйте.

Меня зовут Федор, я технический писатель компании «Цифровая индустриальная платформа». Это совместное предприятие ГК «Цифра» и ПАО «Газпром нефть».

Скажу вам по секрету – сразу хотел вам показать в тик-токовском стиле «10 крутых лайфхаков как писать текст», устроив из этого целый цикл статей/рубрику.

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

Читать далее

Требования ГОСТ на автоматизированные системы в ИБ-проектах. Что изменилось и как это применять?

Время на прочтение17 мин
Количество просмотров144K

Традиционно разработчики документации на автоматизированные системы при создании и обеспечении защиты этих систем применяли ГОСТы 34-й серии. С 2022 года наконец-то произошло обновление старых стандартов в рамках новой серии национальных и межгосударственных стандартов на автоматизированные системы (далее — ГОСТ на автоматизированные системы).

В этой статье мы проясним основные особенности применения ГОСТ на автоматизированные системы, а также разберемся в изменениях, которые произошли в 2022 году.

Читать далее

Стандартизация информационных технологий внутри организации

Время на прочтение8 мин
Количество просмотров7K

С момента выхода блестящей книги Николаса Карра «Блеск и нищета информационных технологий: Почему ИТ не являются конкурентным преимуществом» прошло 16 лет, но за это время мало что изменилось. Затраты на программное обеспечение (ПО) по-прежнему являются настоящей чёрной дырой для бюджетов компаний и государственных органов управления, ведь зачастую их конечный результат практически невозможно увидеть.

Стандартизация используемых программных продуктов (ПП) и их элементов (блоков) — единственно верный способ для организации в несколько раз снизить затраты на ПО и повысить их эффективность.

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

Читать далее

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

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров94K

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

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

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

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

Читать далее

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

Время на прочтение8 мин
Количество просмотров2.3K

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

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

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

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

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

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

Читать далее

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

Время на прочтение14 мин
Количество просмотров7.3K

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

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

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

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

Читать далее

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

Время на прочтение10 мин
Количество просмотров22K

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

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

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

Читать далее

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

Время на прочтение2 мин
Количество просмотров5K

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

Читать далее

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

Время на прочтение10 мин
Количество просмотров2.9K

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

Читать далее

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

Время на прочтение4 мин
Количество просмотров34K

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

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

Читать далее

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

Время на прочтение26 мин
Количество просмотров41K

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

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

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

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

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

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

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

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

Читать далее

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

Время на прочтение3 мин
Количество просмотров29K

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

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

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

Читать далее

Ближайшие события

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

Время на прочтение8 мин
Количество просмотров10K

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

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

Читать далее

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

Время на прочтение3 мин
Количество просмотров2.7K

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

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

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

Читать далее

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

Время на прочтение7 мин
Количество просмотров4.5K

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

Читать далее

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

Время на прочтение11 мин
Количество просмотров35K

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

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

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

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

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

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

Дальше, пожалуйста

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

Время на прочтение13 мин
Количество просмотров8.4K

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

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

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

Читать далее

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

Время на прочтение7 мин
Количество просмотров6.6K

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

Читать далее

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

Время на прочтение3 мин
Количество просмотров7.5K

Часть первая

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

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

Читать далее