Как стать автором
Обновить
27.89

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

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

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

QPR Enterprise Architect: Инструмент моделирования Бизнес-Архитектуры и Процессов Управления

Уровень сложности Простой
Время на прочтение 8 мин
Количество просмотров 1.5K
Обзор
Recovery Mode

Обзорная статья о QPR Enterprise Architect. Основные возможности и преимущества данного инструмента.

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

Новости

ШвабрОпс – новое направление в IT-индустрии

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

Л - Добрый день, дорогие зрители, сегодня мы продолжаем нашу серию репортажей «Стартаперы Кварцевой Лощины». С вами снова я, независимый журналист, Лайер Бала-Больё, и сегодня наш гость - талантливый селфмейд, добившийся всего сам, 19-летний сын известного миллиардера, стартапер Жу̒лико Бары̒гги младший.

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

Жулико, вы только что были спикером на проходящем в Сан-Дьябло Блаблатоне и упомянули такую интересную вещь, как ШвабрОпс - можете рассказать нашим зрителям, что это такое и с чем его едят.

Ж – Привет, Лайер, привет всем. Да, на Блаблатоне я рассказывал про ШвабрОпс – это новое перспективное направление в IT. Дело было так. Я маялс…т.е. интенсивно работал в офисе и обратил внимание, что какой-то очкастый толстый задрот ходит туда-сюда из кабинета в кабинет. Я спросил секретаршу – кто это такой? Она ответила – это наш ДевОпс.

Л – Ага.

Ж – А я, если честно, даже не знаю, кто это такой. Но мне тут же в голову пришла идея. А что, если он возьмет в руки швабру и будет протирать пол, пока ходит туда-сюда.

Л – Угу.

Ж – Ну и все, собственно. Я подумал-подумал и решил – а зачем нам уборщица?! Пусть этот дев…как его там…в общем – пусть он еще и пол протирает параллельно. Это же какая экономия получается!  

Читать далее
Всего голосов 51: ↑38 и ↓13 +25
Комментарии 82

Важность документации в работе DevRel

Уровень сложности Простой
Время на прочтение 5 мин
Количество просмотров 354
Перевод

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

Читать далее
Всего голосов 16: ↑13 и ↓3 +10
Комментарии 1

«В ближайшие 6 лет требования к системным аналитикам вряд ли сильно изменятся»

Уровень сложности Простой
Время на прочтение 9 мин
Количество просмотров 6.5K
Интервью

О будущем системных аналитиков, о ChatGPT и LLM, что не заменит аналитиков, слишком большом списке требований, что добавить в резюме, low-code/zero-code системах, стажировках и ветках прокачки, поговорили с Алексеем Лобзовым, руководителем направления развития компетенции системного анализа в Альфа-Банке.

Читать далее
Всего голосов 24: ↑23 и ↓1 +22
Комментарии 2

Истории

Список желаний или как EIR приводит к взаимопониманию

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

Всем, привет! Меня зовут Алёна Барыкина и я методолог отдела информационного моделирования департамента цифровизации инвестиционно-строительных проектов компании "Bimeister". И сегодня, хочу с вами поделиться важным аспектом исполнения желаний в проектной деятельности с использованием цифрового информационного моделирования

Вы, конечно же, знаете ключевой принцип успеха любого проекта, включая создания цифровой информационной модели (ЦИМ) - «Начинай только тогда, когда результат уже в уме». Выражение, которое отражает саму суть любой проектной деятельности.

Только вот вопрос - а что каждый участник процесса понимает под необходимым результатом в проекте создания цифровой информационной модели?

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

Когда Заказчик говорит, что ему нужна цифровая информационная модель, он говорит не просто о модели, а о преимуществах, которые он хочет получить с помощью ЦИМ:

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

Немного визуала никогда не повредит повествованию. Краткая история презентаций

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

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

Когда в 1987-м году был продемонстрирован PowerPoint, презентации изменились навсегда. Конечно, развитие презентаций было делом рук не только Microsoft. Пожалуй, самая запоминающаяся презентация всех времён — анонс Стива Джобса iPhone на Macworld 2007 — сделана вовсе не на PowerPoint.

Когда ПО для презентаций стали популярными, такие инструменты, как диафильмы и слайд-проекторы, превратились в хлам в кладовке. До компьютеров презентации делались с помощью флипчартов и слайд-проекторов, и они применялись в учебных заведениях и конференц-залах по всему миру. Интересно, что дизайн слайдов олицетворял визуальный стиль графического дизайна своего времени. Эволюция презентаций следовала тенденциям, так же как реклама и мода. В этой статье рассмотрим, как искусство презентаций развивалась с течением времени и как она превратились в то, что мы знаем сегодня.
Читать дальше →
Всего голосов 27: ↑23 и ↓4 +19
Комментарии 2

Рассказ о том, как QA решили документацию тестировать

Уровень сложности Средний
Время на прочтение 6 мин
Количество просмотров 4.9K

Давай определим, зачем это вообще нужно?

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

Press me senpai
Всего голосов 11: ↑11 и ↓0 +11
Комментарии 13

Architecture as Code: реализуем подход Саймона Брауна

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

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


  1. Модели архитектуры программного обеспечения как код, построенные с использованием Structurizr Lite
  2. Документация, созданная с помощью шаблона Arc42
  3. Журнал решений, созданный с помощью ADR Tools

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


Читать дальше →
Всего голосов 10: ↑9 и ↓1 +8
Комментарии 3

Docs as Code: как вести фронтовую документацию рядом с кодом, чтобы репозиторий не раздуло

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

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

Но, кажется, эту напасть удалось побороть. В статье я расскажу, как вести фронтовую документацию рядом с кодом и к каким последствиям это приводит.

Читать далее
Всего голосов 32: ↑32 и ↓0 +32
Комментарии 5

UML: обзор основных типов диаграмм, диаграмма компонентов. Часть 2

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

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

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

Современные подходы к созданию интересной и эффективной технической документации в современной индустрии

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

«....всё это действенные методы для улучшения разработки интересной и эффективной технической документации....»

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

Postman как инструмент документации

Уровень сложности Средний
Время на прочтение 9 мин
Количество просмотров 7.4K
Туториал

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

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

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

📦 Читать далее
Всего голосов 4: ↑4 и ↓0 +4
Комментарии 4

ИТ – Как быть с документацией?

Уровень сложности Средний
Время на прочтение 7 мин
Количество просмотров 7.1K
Мнение

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

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

Готов уделить время на чтение
Всего голосов 5: ↑4 и ↓1 +3
Комментарии 9

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

Битва пет-проектов
Дата 25 сентября – 30 ноября
Место Онлайн
PG Boot Camp Russia 2023
Дата 5 октября
Время 10:00 – 17:00
Место Москва Онлайн
Joker
Дата 9 – 14 октября
Время 16:00 – 19:30
Место Санкт-Петербург Онлайн
Открытый урок «Kafka Streams»
Дата 16 октября
Время 10:00
Место Онлайн
Питч-сессия pravo (tech) impulse
Дата 19 октября
Время 15:45 – 17:30
Место Москва
Russia Risk Conference 2023 — 19-я конференция по риск-менеджменту
Дата 25 – 26 октября
Время 10:00 – 19:00
Место Москва Онлайн
Онлайн IT HR-конференция HR42
Дата 17 – 18 ноября
Время 10:00 – 14:00
Место Онлайн
HighLoad++ 2023
Дата 27 – 28 ноября
Время 9:00 – 20:00
Место Москва Онлайн

Как разработать техническую документацию, которая точно будет работать. Часть 2. DocOps в действии

Время на прочтение 28 мин
Количество просмотров 2.6K
Туториал

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

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

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

Что же, начнем!
Всего голосов 8: ↑8 и ↓0 +8
Комментарии 14

Die But Do: теханализ и почему без него разработка обречена на провал

Уровень сложности Простой
Время на прочтение 6 мин
Количество просмотров 2K
Туториал

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

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

Узнать про теханализ
Всего голосов 2: ↑2 и ↓0 +2
Комментарии 1

«У нас с этим контрагентом дружеские отношения» или как остаться без документации на проекте

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

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

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

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

Читать о приключении "друзей" далее
Всего голосов 14: ↑12 и ↓2 +10
Комментарии 4

Как документировать публичные API для продукта. Большой гайд, часть 1

Уровень сложности Средний
Время на прочтение 17 мин
Количество просмотров 7.3K
FAQ

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

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

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

Читать далее
Всего голосов 7: ↑6 и ↓1 +5
Комментарии 3

Процесс работы системного аналитика: практическое руководство, примеры и шаблоны

Уровень сложности Средний
Время на прочтение 12 мин
Количество просмотров 12K
Туториал

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

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

Читать далее
Всего голосов 6: ↑5 и ↓1 +4
Комментарии 3

Что проще писать — документацию или код?

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

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

Читать далее
Всего голосов 5: ↑1 и ↓4 -3
Комментарии 1

Как составить ТЗ программистам для запуска чековой промоакции с геймификацией розыгрыша призов

Уровень сложности Средний
Время на прочтение 6 мин
Количество просмотров 864

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

Читать далее
Всего голосов 8: ↑3 и ↓5 -2
Комментарии 3

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