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

В статье предложены некоторые приемы форматирования текста, которые могут существенно облегчить оформление документов, разрабатываемых по ГОСТам, техническим писателям и всем, кто занимается разработкой таких документов. Подходы к автоматизации форматирования текста Приложений документов рассматриваются на примере ГОСТ 7.32-2017 в редакторах MS Word и LibreOffice Writer. Предполагается, что читатель знаком со стилями, применяемыми в этих редакторах, и активно их использует в повседневной работе.

Когда вы в последний раз сталкивались с качественно документированным кодом?

С кодом, который можно было использовать буквально «из коробки», просто ознакомившись с небольшим README файлом. Но к которому в то же время прилагалась подробная документация, поясняющая каждую строчку: не только то, что она делает, но и почему она была написана именно так, а не иначе.

Давно ли вы встречали такой код? Неделю назад? Месяц? Год?

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

Но разве можно винить в этом разработчиков?

Плагины 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.