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

Привет! Хочу поделиться парой мыслей о представлении нефункциональных требований в формате User Story. Вы наверняка помните самый распространенный шаблон для историй. В шаблоне есть три части «кто», «хочет что», «чтобы что». Чтобы соблюдать такой формат, важно выделить действующие роли и цели для каждой истории. Для нефункциональных требований это бывает непросто и я часто думаю: «А нужно ли?».

Майк Кон в своем блоге пишет, что нефункциональные требования хорошо ложатся в стандартный шаблон пользовательской истории и что такой шаблон позволяет не забыть, почему это требование появилось. В статье «Нефункциональные требования как пользовательские истории» (Non-functional Requirements as User Stories) приведены кейсы, среди которых есть несколько «синтетические». Например, на мой вкус странно выглядит история вида «Как человек, говорящий на одном из латиноамериканских языков, я, возможно, когда-нибудь захочу запустить ваше программное обеспечение». Как работать с такой историей в бэклоге? Сможет ли команда адекватно ее декомпозировать на атомарные задачи?

Обычно бывает интересно почитать не только саму статью в блоге, но и комменты к ней. В комментариях к статье Майка Кона как раз есть похожие вопросы:

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

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

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

В данной статье мы рассмотрим ключевые аспекты оформления документации в Git репозитории, обсудим лучшие методики и практики для создания качественной документации. Независимо от того, являетесь ли вы опытным разработчиком или новичком в области Git, эта статья поможет вам создать четкую, структурированную и информативную документацию для вашего проекта. Погружайтесь в мир оформления документации, улучшайте ваши проекты и делитесь своими идеями с сообществом разработчиков Хабр!

Я столкнулся с тем, что я иногда не понимаю код, с которым мне приходится работать. И это сильно сказывается на моей производительности и на качестве конечного результата. Неделю назад я прочитал статью Плохо девелопмент за авторством @dalerank(Сергей Кушниренко), в которой описывается проблема молодых специалистов, которые упрощая себе работу пользовались готовыми решениями, а не писали код с нуля. Моя статья не об этой статье и не ответ к ней. В самой статье Сергея Кушниренко была ссылка на другую статью - You should refuse to develop what you don’t understand. И вот эта статья меня несколько озадачила. Я задумался о проблеме понимания того, с чем я работаю. О ней я бы хотел написать, но и некоторые тезисы из статьи Сергея Кушниренко я тоже затрону.

ВНИМАНИЕ! Дальше вас ждет душная простыня текста без юмора.

Привет! Меня зовут Дмитрий Миронюк, я старший технический писатель в компании Bercut. До этого работал системным администратором, специалистом внедрения и поддержки, программировал IP-телефонию, успел поработать тимлидом. Но как в итоге стал техническим писателем расскажу в другой раз. Сегодня поговорим о ревью и комментариях. Приведу реальные примеры из личного опыта, а также поделюсь наблюдениями, как процесс ревью повлиял на мое сознание.

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

— Видишь суслика?

— Нет…

 — И я не вижу. А он есть!

Одним из мощных и удобных инструментов текстовых редакторов является скрытый текст. Этот инструмент имеется практически во всех редакторах. Самым популярным и совершенным редактором на данный момент является MS Word. Поэтому некоторые возможности скрытого текста рассмотрены на его примере.

Всем привет! Меня зовут Ксения Непомнящая, я — технический писатель в команде Zyfra Mass & Energy Balance (Z-MEB) компании «Цифровая индустриальная платформа». Z-MEB — это продукт для предприятий добычи и переработки нефти, газа и руды, участвующий в программе импортозамещения. Сегодня предлагаю вам взглянуть на пользовательскую документацию как на путеводитель по продукту и рассмотреть ее роль в увеличении ценности продукта.

Понятный интерфейс как город с понятной планировкой и развитой инфраструктурой

Представим себе город с понятной планировкой и развитой инфраструктурой и рассмотрим два варианта взаимодействия с ним.

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

ArchiMate предоставляет общий и унифицированный способ изображения и анализа архитектур предприятий. Разработанный The Open Group, этот открытый и независимый язык моделирования предлагает визуальное представление отношений между различными компонентами в организации. Язык разработан интуитивно, что делает его доступным как для технических, так и для неспециалистов. Нотация ArchiMate основана на последовательной структуре, что позволяет аналитикам создавать ясные, краткие и стандартизированные модели.

Всем привет! Меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT более 10 лет.

Сегодня разговор пойдет про документ "Общее описание системы".

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

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

Правильно довести идею до разработки поможет техническое задание. Зачем готовить ТЗ, кто и как должен это делать, можно ли обойтись без ТЗ и как минимизировать расходы – обо всем этом вы узнаете из данной статьи.

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

Кому будет полезна эта статья:

1. Тем, кто начинает свой путь в IT-предпринимательстве, но не знаком с технической стороной вопроса.

2. Начинающим менеджерам IT-проектов, которые пока не имеют опыта в постановке задач подрядчикам.

3. Владельцам уже существующих проектов, которые нуждаются в дополнениях/доработках.

В технической документации часто встречаются фразы с использованием страдательного залога. Параметры там «задаются», файлы «сохраняются», а программа «запускается». Ох, опасная эта форма для строгих и однозначных описаний! Почему же страдательный залог заставляет читателей страдать? Будем разбираться...

Всем привет! Меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT более 10 лет.

Рассмотрим подробнее.

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

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

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

С чего же начать, если перед вами такие минимальные бизнес требования?

Привет, Хабр! Я Ульяна, старший аналитик в направлении продуктового и системного анализа в отделе Tinkoff Mobile Core. Наш отдел разрабатывает общие технические решения — библиотеки, которые используются в мобильных приложениях экосистемы Тинькофф.

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

Документацию мы ведем в Confluence — и обычно, когда я рассказываю про Confluence, у многих он вызывает, мягко говоря, неприятные ассоциации. Миллион разделов, неудобная навигация, портянки бесконечного текста и многое другое, что отбивает желание даже открывать любую wiki. Но я спешу вас обрадовать — все может быть совсем иначе!

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

Всем привет! Меня зовут Мишинёва Екатерина, я – ведущий технический писатель с опытом работы в сфере IT более 10 лет.

Поговорим о структуре Технического задания.

Резюме.
В статье дается ссылка на файл в формате ODT (основной формат файлов, используемый в текстовом редакторе LibreOffice Writer), содержащий макросы на «родном» для LibreOffice языке программирования макросов BASIC, которые осуществляют экспорт текста из LibreOffice Writer в новый файл в формате Habr Flavored Markdown (далее - HFM) или HTML, в виде, пригодном для размещения статьи в интернете, например, на сайте habr.com.

Текст данной статьи был экспортирован в формат HFM для размещения на сайте habr.com с помощью библиотеки макросов, содержащихся в данном файле.

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

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

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