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

Postman в основном известен в качестве мощного инструмента для тестирования API. Но он также может значительно облегчить жизнь новым членам команды, аналитикам и клиентам, которые интегрируются с вами.

В этой статье я, SDET-специалист SimbirSoft Дарья, проведу обзор функций, с помощью которых Postman может помочь каждой из этих групп. Покажу на небольших примерах, как превратить набор запросов в то, что не стыдно будет пошарить коллегам, взаимодействующим с вашим API, и упростит жизнь новоприбывшим членам команды. Эта статья будет полезна специалистам различных уровней как в ручном, так и в автотестировании, а также бизнес- и системным аналитикам, для которых Postman сможет быть полезным для работы с документацией. 

Примеры буду приводить на ставшем классикой тренажере для практики отправки REST-запросов Petstore Swagger. Это имитация онлайн-зоомагазина, где можно манипулировать информацией о питомцах пользователей, а также создавать заказы.

Документация в рамках ИТ-проекта/продукта подчас имеет необычное исполнение. Есть проекты/продукты, где на первый взгляд с документацией всё хорошо, она выходит в рамках обязательств по контракту, но вот применять её очень сложно. Бывают и обратные примеры, когда документация оформлена отлично и написана грамотно, в ней всё понятно, но она очень сильно устарела. Иногда случается всё и сразу.

Не всегда понятно, как включить нового сотрудника в работу? Новичку приходится отвлекать более опытных коллег. Самый удивительный случай, это когда в ИТ-проекте/продукте существует свой мифический «Петрович», который знает, что как устроено, и может помочь освоиться.

Привет! Меня зовут Андрей Гладилин, я работаю в Swordfish Security над составлением технической документации для ИТ-решений. Завершая  предыдущую статью, мы обсудили преимущества и недостатки DocOps-подхода к разработке технической документации и немного поговорили о прикладной реализации этой парадигмы — Doc-as-code.

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

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

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

Меня зовут Евгений Шалаев. Я Frontend-разработчик в команде СберЗдоровье. В этой статье я расскажу о теханализе в разработке, его пользе, принципах выполнения и своем опыте проведения подобных исследований.

Вот такой дружной и весёлой командой стартовал новый проект, в котором потом «друзья» не смогли договориться.

История о том, почему необходимо поддерживать деловую коммуникацию с исполнителем, а также вести документацию на проекте.

Простые истины с высокой ценой ошибки.

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

Материала вышло многовато, поэтому разбил его на 2 части. В части 1 (этой статье) рассмотрим, почему и зачем вообще публичным API нужна документация, есть ли у нее какие-то отличия от документации внутренних API, а также проанализируем и детально разберем различные подходы к ведению такой документации, попутно познакомившись поближе с полезными инструментами.

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

Лучший способ понять теорию — получить больше опыта в разных проектах. Для системных и бизнес‑аналитиков я постоянно показываю подходы к работе через публикацию разборов задач: БД, API, Интеграции, требования, и все, что связано с проектированием систем.

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

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

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

Всем привет, меня зовут Динара!

В компании Бимэйстер я являюсь Старшим техническим писателем и хочу рассказать немного о правилах оформления технической документации.

Введение

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

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

Нормоконтроль – на первый взгляд отголосок из Советского Союза или что-то связанное с Госзаказчиками. Но нормоконтроль (далее по тексту НК) – гигиена документа. 

НК включает в себя не только правила русского языка (синтаксис/орфография), но и требования перекликающиеся с ГОСТ.  

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

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

В статье обозначу проблему, связанную с ведением фронтовой документации рядом с кодом, и приведу одно из решений на базе Git LFS. Затем поделюсь результатами двух пилотов, проведённых в Банке во втором квартале 2023. Их результаты помогут оценить влияние Git LFS на опыт ведения фронтовой документации рядом с кодом. Статья подойдёт всем, кто занимается подготовкой технической документации на программные продукты.

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

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

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

Рассмотрим, что такое 3D сканер, как он работает, каким бывает. Здесь нужно отметить, что мы 3D сканеры не продаем и не покупаем. В нашей организации нет собственных 3D сканеров по той простой причине, что это оборудование достаточно дорогое, а используется далеко не каждый день. Соответственно, намного экономически целесообразнее просто его брать в аренду, когда это нужно. В Петербурге и в Москве таких компаний достаточно. Оборудование сдается в аренду вместе с операторами. Стоит это в районе 30 тысяч рублей за день работы, условно за восьмичасовую смену. При необходимости оператор со сканером может выехать в командировку в любой уголок страны.

Привет! Я Марина Виноградова, технический писатель VK. Прочитав название этой статьи, вы подумаете: «Документация же не пахнет!» Это правда, если речь не о её бумажных копиях… Но почему тогда пахнет код? Запахи кода — это фигура речи, обозначающая признаки проблем в коде и необходимости рефакторинга. Запахи кода обращают внимание на недочёты в проектировании и говорят нам о низком качестве кода. Мы можем написать как код, так и документацию. Чистыми с первого раза они никогда не будут, нужно пропускать их через рецензирование или рефакторинг.

Рассмотрим, как основные запахи кода с ресурса Refactoring Guru (сейчас он запрещен на территории РФ) ложатся на документацию. Это лишь малая часть того, на что стоит обращать внимание при её разработке.

Меня зовут Марина, я работаю техническим писателем в ГНИВЦ. Еще с детства я любила делать доклады в школе, а где все пишут доклады? Word! Именно с тех времен началась моя история дружбы с данной программой.

Сегодня я хочу поделиться с вами о работе перекрестных ссылок. Вроде бы ничего сложного, если бы не одно НО! Как раз об этом «НО» и будет моя статья.

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

Лично мне завесу тайны приоткрыл Альфа-Банк, здесь документация ведется рядом с кодом, и схемы логичнее описывать тоже кодом. Но это не так страшно и не так сложно (почти) как кажется. Давайте я приоткрою ящик Пандоры и сниму кармическое проклятье с  этого инструмента. 

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

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

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