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

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

При обсуждении какого-то явления, полезно сначала посмотреть на его определение. Тут нам поможет старая добрая Википедия:

“Письменный текст или иллюстрация, которая сопровождает программное обеспечение или интегрирована прямо в исходный код. Документация объясняет, как работает ПО или как его использовать. Может иметь разное значение для людей с разными ролями в команде”

Определение действительно неплохое, в нём содержится несколько важных свойств документации.

Ранее я писала о том, как мы внедряли корпоративную систему управления контентом, с помощью которой удалось объединить более 200 сотрудников из разных департаментов. В этот раз расскажу непосредственно о процессе техдокументирования. Сегодня я покажу путь развития технической документации с нуля на примере PT Application Firewall и поделюсь инструментами, которые помогают нам ее делать.

Даже сложные картинки часто читаются проще чем, простые столбики связанных данных (например, взаимосвязанных табличек). Такова особенность восприятия человека. Поэтому он постоянно пытается данные (знания) визуализировать в графике. В принципе любой граф с информацией к узлам или ребрам (сеть сущностей, их семантические типы, свойства и отношения) можно «громко» назвать графом связанных данных и даже Графом знаний (Knowledge graph).

Точных определений «Связанные данные» и его направления Knowledge graph – полагаю, что нет, поэтому не углубляясь в теорию, обозначим лишь базовый принцип «Связанных данных»: «субъект – связь (предикат) - объект» (тройки , triples). Принцип лежит во всех прикладных задачах визуализации этих самых «троек»: анализ больших графов (Gephi, Cytoscape), BPM (ARIS, ARPO), «графовые» Zettelkasten (Roam Research, Obsidian, Loqseq) - Personal Memory Manager / Personal Knowledge Management (TiddlyMap), всевозможные концептуальные - ментальные карты (мозгового штурма, карты разума mind-map) и заканчивая semantic Web. 

Написать данный материал меня побудила статья «Нам он и нафиг не нужон, технический писатель ваш!» (с) или для чего он вам всё-таки нужен» (далее – Статья) и он является отчасти ответом на некоторые мысли, озвученные в ней, а также содержит информацию о моем видении работы технического писателя (далее – ТП). Поэтому также приглашаю автора Статьи @champ_7777777 к прочтению.

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

Почему команда косячит и что-то идет не так? Мы задались этим вопросом и ретроспективно посмотрели на последний год работы. В этой статье я, Артем Салеев, руководитель backend-направления, расскажу о 3 основных проблемах в работе команды и поделюсь, как на опыте компании мы с ними разобрались.

Статья написана на основе моего выступления на конференции Merge 2022.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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