Всё о деятельности технических писателей
Плагины VS Code, без которых техническим писателям и разработчикам документации жить можно, но сложно. В подборке — линтеры, форматирование, работа с git, проектирование API, подготовка схем и милота для удобной разработки.
Краткий разбор типичных ошибок и когнитивных искажений при написании технической документации для разработчиков. Обнаружение и hotfix этих дефектов призван сделать ваши тексты лучше, а процесс работы с ними — чуть более осознанным.
Анна Вичугова, CBAP, написала стартовое пособие по тому, как начать моделировать бизнес-процессы в BPMN
1. Назначение BPMN.
2. Уровни моделирования.
3. Алфавит нотации: События, Логические операторы, Артефакты.
4. Правила построения диаграмм.
5. Пример построения диаграммы по тексту.
6. Рекомендуемые инструменты.
В MS Visio начиная с версии 2007 появилась возможность называемая «темы» (со слов разработчиков она предназначена «для придания схеме профессионального вида»)…
В этой статье вы узнаете как удалить «нежелательное влияние» тем в документах MS Visio.
Одним из первых шагов при написании ТЗ на разработку ИС является выявление будущих пользователей системы. Казалось бы: ничего сложного, но бывают нюансы.
Давайте начнем с теории. Согласно Карлу Вигерсу существует множество заинтересованных лиц:
«Заинтересованное лицо (stakeholder) — это человек, группа или организация, которая активно задействована в проекте, подвержена влиянию процесса или результата или может влиять на процесс или результат.»
их подмножество — клиенты:
«Клиенты являются подмножеством заинтересованных лиц. Клиент (customer) — человек или организация, получающая от продукта прямую или косвенную выгоду. Клиенты это заинтересованные в проекте лица, запрашивающие, оплачивающие, выбирающие, определяющие, использующие и получающие результаты работы программного продукта».
и их подмножество — пользователи:
«Требования пользователей определяют те, кто прямо или косвенно взаимодействуют с продуктом. Эти пользователи (часто их называют конечными пользователями) являются подмножеством клиентов. Прямые пользователи непосредственно работают с продуктом. Непрямые пользователи могут получать результаты работы системы, не входя в непосредственный контакт с ней.»
Все эти подмножества я представила кругами Эйлера на рисунке ниже.
Судебные споры в области ИТ широко распространены в США, имеют наработанную практику и устоявшиеся подходы при разрешении такого рода вопросов. Постепенно подобные иски появляются и у нас, выводы из таких судебных решений можно имплементировать в собственную практику.
Проблема аппаратного представления программных функций
Первым в обзоре будет дело «Патент на кнопку «SOS» RU141791, АРТАШЕС ИКОНОМОВ vs APPLE.
Существует один из подходов к написанию заявок в сфере информационных технологий, когда предлагаются шаги/признаки способа (алгоритма или некий функционал программного продукта) представить в виде аппаратных блоков или модулей, которые соединены между собой или имеют связь с какими-либо другими устройствами.
Есть разные подходы к ведению требований к ПО: одни пишут полноценные сценарии использования, другие выбирают пользовательские истории, а третьи — вообще избегают формализации требований, считая это пустой тратой времени.
Но я так не считаю. Формализация — большой и важный этап разработки требований. В статье расскажу: как происходит ведение требований у нас, какие этапы мы проходим, каких правил придерживаемся и что будет, если отклоняться от правил. Если вы системный или бизнес-аналитик, владелец продукта или просто работаете с требованиями к программному обеспечению, то эта статья для вас.
Я работаю техническим писателем в компании documentat.io. Мы занимаемся заказной разработкой технической документации, в том числе на английском языке. Иногда я дорабатываю уже существующие документы или спецификации к API на английском. Как правило, такие документы написаны русскоязычными разработчиками, которые неплохо владеют английским. И всё же они часто допускают характерные грамматические, пунктуационные и стилистические ошибки.
Корень этих ошибок один — разные языковые механизмы. Нам бывает легко запутаться в употреблении временных форм, порядке слов или непонятно зачем придуманных артиклях.
Поэтому в этой статье я постарался не просто дать рекомендации о том, как можно избежать распространённых ошибок, но и подсветить те отличительные черты английского языка, которые к этим ошибкам приводят.
Казалось бы, с документацией всё просто — пишешь, публикуешь, поддерживаешь актуальность. Например, вот у нас в Ozon есть пользовательские инструкции на docs.ozon.ru: выглядит просто как текст на сайтике, что ж необычного-то в его размещении и в целом в работе техписателей?
Если начать раскапывать, всплывёт ещё несколько вопросов:
• где хранить тексты и почему Confluence не подходит?
• как красиво оформить документацию с помощью статических генераторов сайтов
• зачем техписателям знать git и CI/CD?
• в какой момент пора искать разработчиков в команду и превращать документацию в платформу?
На связи Катя — руководитель отдела технических писателей в Ozon, и сегодня расскажу о платформе Docs Ozon изнутри.
Стайлгайд обеспечивает консистентность текста, ускоряет адаптацию новых сотрудников и экономит время, сводя к минимуму дискуссии о том, как правильно писать или оформлять текст.
Здравствуйте. Меня зовут Евгений Пригаров, я руководитель программы проектов в ГК Юзтех. С 2006 года я занимаюсь оценкой проектов, работал на пресейлах в 4-х компаниях разного масштаба. В совокупности за эти годы я отработал 1000+ пресейлов.
В этой статье я хочу поделиться своим личным опытом, подходом и рекомендациями к оценке проектов и созданию технико-коммерческих предложений (ТКП). Эти рекомендации довольно простые и, возможно, покажутся банальными, но на мой взгляд, они хорошо работают. Они позволяют разумно и эффективно использовать время и возможности.
Из статьи вы узнаете:
1) Как качественно оценить проект?
2) Как создать качественное ТКП?
3) Как качественно подать результаты оценки?
Дисклеймер:
— Качественная оценка и ТКП не гарантируют победы в пресейле;
— Качественная оценка и ТКП не гарантируют успешного выполнения проекта. Чтобы проект был выполнен успешно, нужно и на всех последующих этапах проекта отрабатывать возникающие задачи на пределе своих возможностей.
Привет! Меня зовут Владимир, но вы можете звать меня просто Иннокентий Алексеевич. Я люблю эксперименты. Сегодня я расскажу, как можно улучшить навигационное меню на сайте документации, сократить время сборки и размер сайта больше чем в два раза. В качестве примера возьму сайт документации, собранный при помощи Antora.
Кому будет полезен материал: техническим писателям, разработчикам сайтов документации и просто любителям опенсорса и красивых вещей.
Antora — генератор статических HTML сайтов из исходных AsciiDoc файлов. Antora бесплатная и имеет открытый исходный код.
Мой мадригал тем инструментам разработки, которые изменили мою жизнь
Программирование стало гораздо более многогранным ремеслом с тех пор, как в середине 1990-х я впервые попробовал AmigaBASIC. В те времена еще можно было купить один большой том о компьютере, на котором вы программируете – и там бы нашлось 99% всей нужной информации. Эта книга, где на множестве страниц уголки загнуты в качестве закладок, обклеенная стикерами, лежала бы у вас под рукой, пока вы вбивали бы команды в монохромный текстовый редактор.
Современная книга по клиентскому веб-фреймворку может быть толще, чем во времена программирования под C64 бывали мануалы, достаточные для создания полноценных игр. С другой стороны, сегодня информация по любым платформам, для которых требуется писать код, находится буквально в одном клике.
Сегодня никто бы больше и не подумал покупать документацию по разработке – и Microsoft, и Apple свободно выкладывают свою документацию в Интернете для всех желающих. А что говорить о проектах с открытым исходным кодом!
Во времена npm, PyPI и GitHub сложно объяснить, насколько неоднозначным решением (которое требовалось всесторонне обдумывать) раньше считалось потребовать хоть какие-нибудь возможности, которые выходили бы за рамки функционала операционной системы. Часто вместе с продуктом приходилось сдавать и все его зависимости.
Я в системном анализе уже более 5 лет. За эти годы я достигла значительного роста как горизонтального, так и вертикального. Ежедневно я взаимодействую и консультируюсь со своими коллегами, обращаюсь к их техническим заданиям, разбираюсь в их методах реализации и наставляю новых сотрудников. В начале этого года я поймала себя на мысли, что невольно стала разделять своих коллег на 3 типа системных аналитиков.
Такая градация помогает мне определить подход взаимодействия со специалистом. А также позволяет спрогнозировать, каких результатов от этого сотрудника можно ожидать.
Эта статья будет интересна системным аналитикам и участникам команд разработки. А если среди ваших коллег есть люди, подходящие под моё описание, то, возможно, вы будете понимать их чуточку лучше.
Разработка современного софта это далеко не только про код.
Разработка современного софта это во многом про ToolСhain(ы). Прежде чем начать исполняться исходники проходят гигантский путь. C каждым поколением выходят все более и более массивные системы сборки.
Современные технологии разработки софта это многостадийные конвейеры из различных утилит. Понять их весьма сложно. Однако поможет нам в этом хипстерский язык программирования Graphviz.
Привет, Хабр! Меня зовут Елена, я ведущий аналитик ИТ-компании SimbirSoft. Сегодня хочу затронуть такую тему, как нефункциональные требования к ИТ-продукту, которым не всегда уделяется должное внимание, а зря. Их несоблюдение может привести к потере прибыли, клиентов, репутации, остановке производственных процессов и большим штрафам, хотя с первого взгляда их влияние на осуществление пользовательского функционала неочевидно.
В статье расскажу, как и почему это может произойти, а главное – что нужно учесть, чтобы избежать негативных последствий. Материал будет полезен аналитикам, командам разработки, а также владельцам продуктов, поскольку они больше всех разбираются в системе и заинтересованы в успехе проекта. Приятным бонусом станут чек-листы, которые помогут сформулировать наиболее важные нефункциональные требования к:
- мощности и производительности
- безопасности, соответствию стандартам и законодательству
- переносимости и совместимости.
Всем, кто создавал библиотеки или сервисы с публичным API хорошо знакома боль, когда документация отстает от изменений в коде и рутинный процесс обновления документации на сайте становится настолько неинтересным, что про него просто забывают. Можно ли как-то автоматизировать генерацию технической документации (а в идеале еще и создание руководства пользователя с возможностью навигации и красивыми картинками)? В этой статье мы обсудим возможности Dokka (Kotlin-инструмента для создания документации) и подходы к генерации артефактов документации с использованием плагинов Gradle.
Недостаточно просто написать инструкции — важно, как, в каком порядке и где вы их разместите.
Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками: инфраструктурой as a service; фреймворками и библиотеками; инструментами для работы с базами данных и аналитикой и прочим. Сотни инженеров ежедневно обращаются к нашим сервисам и нуждаются в их описании.
Опираясь на свой опыт, я пошагово расскажу, как привести в порядок документацию технической команды, чтобы избавить коллег от однотипных вопросов и наладить межкомандную коммуникацию.