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

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

Меня зовут Евгений Шалаев. Я 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-ти лет назад и не претерпевал с тех пор никаких существенных изменений.

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

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

Я решил опробовать метод «грубого вмешательства» при необходимости замены шрифтов используемых в стилях документа MS Word.

Данная статья опубликована в хабе Подготовка технической документации, поэтому в ней не содержится лютого хакинга и прочего колдунства…

Хабр, привет! Меня зовут Витя, я работаю системным аналитиком, сегодня хочу рассказать про такой обязательный навык аналитиков, как проектирование процессов. Думаю, что каждый, кто будет работать на позиции системного/бизнес аналитика, рано или поздно столкнется с такой задачей.

Помните историю про "танцующий" мост? Эти тёплые времена, когда новости были просто интересными, а не вызывали посттравматическое расстройство...

В этой статье посмотрим, как выполняются инженерные расчёты и почему мост пустился в пляс. Добро пожаловать в наш инженерный клуб!