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

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

Можно встретить много  примеров того как применять customer development, который опирается на “персоны”,  для B2C, B2B продуктов, даже для B2BC решений, но сегмент продуктов внутреннего потребления как правило скрыт от посторонних взглядов. Их чаще называют проектами по “автоматизации бизнес-процессов”, которые решают задачу для внутреннего клиента. Особенностью таких проектов/продуктов является секретность, неотвратимость пользования создаваемым продуктом (как считают многие оптимизаторы) и возможность “дотянуться” до потребителя рукой.

В статье аккумулированы некоторые типичные ситуации, выстраданные многолетней практикой по автоматизации бизнес-процессов в десятке отраслей, где я побывал на разных ролях: от business analyst до product manager. Ключевый объект суммирирования опыта — люди, а именно знаниях об их осознанных или неосознанных потребностях, которые являются отправной точкой улучшений.

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

В этот раз мы рванем сразу с места в карьер и попробуем расширить профиль пользователя в Xwiki.

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

Эта статья продолжает цикл публикаций о российских BIM-технологиях и посвящена программному комплексу Model Studio CS Технологические схемы, предназначенному для решения задач разработки схемных решений при проектировании разделов ТХ.

Введение

На первый взгляд разработка схемных разделов технологических решений может показаться простой и довольно тривиальной задачей. Результат в виде получившейся схемы всегда представляется простым и понятным. Но когда понимаешь, что внесенная информация и решения, принятые на этом этапе, проходят через все стадии проекта, становится ясно – для эффективной работы и сокращения числа возможных ошибок необходим удобный и надежный инструмент. Инструмент, который автоматизирует стандартные операции и позволит не отвлекаться от процесса проектирования. Такой, каким в полной мере является программный комплекс Model Studio CS Технологические схемы.

JSDoc - это язык разметки, используемый для аннотирования исходного кода JavaScript с использованием комментариев. Аннотации обрабатывается различными инструментами для создания документации в доступных форматах, таких как HTML и Rich Text Format.

Всем привет! Меня зовут Семен. Я Java-разработчик и руководитель группы Java-разработки в Центре Big Data компании MTS Digital. В этом посте я хочу поговорить о Release Notes. Что это такое, почему не стоит писать их вручную и какие есть способы автоматизации. Покажу и реальный пример того, как организована  работа с Release Notes в нашем проекте.

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

Хочу очертить тот путь, который мы прошли, и рассказать о том, какие решения принимали, и что из этого вырастало.

Привет! Меня зовут Катя, я руководитель команды технических писателей в Ozon.

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

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

Hello World!

Меня зовут Сергей Павлов, я тимлид по системной аналитике в банке "Открытие” на продукте МСБ “Бизнес-Портал”. Хочу рассказать, как я решал задачи по управлению командой, когда к ней присоединился.

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

Итак, морозное утро, вежливый голос руководителя мне говорит: “Это команда системных аналитиков, начинай творить добро”. Я смог выдавить только “угу” и сел думать насчет того самого творить и того самого добра.

Привет! Меня зовут Наталья и я DocOps-инженер в компании Yadro.

Я планирую выпустить цикл статей об этой профессии на примере Yadro. Первая статья носит обзорный характер, последующие будут более техническими и содержать примеры реальных кейсов, с которыми приходится сталкиваться во время работы.

Немного о себе

Я окончила механико-математический факультет, во время учёбы занималась матмоделированием в области авиастроения, затем семь лет работала инженером по локализации и техническим писателем в Xsolla, потом полтора года в роли руководителя команды автоматизации, и вот я DocOps в компании Yadro.

Всем привет! Мы продолжаем разбирать наши решения. Сегодня расскажем о том, как, используя генератор Material for MkDocs, можно создать несложный, но удобный статический сайт с документацией (и не только!).

А ещё как встроить его в CI/CD для автосборки и автопубликации (мы используем Gitlab CI, о чём подробно рассказывалось в предыдущем туториале), а также как использовать плагины к генератору чтобы, к примеру, создавался не только сайт, но и его pdf-представление.

Добро пожаловать под кат!

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

Привет, меня зовут Татьяна, я — старший технический писатель в Центре разработки Orion Innovation. Недавно нам пришлось переводить в Agile крупный проект. Несколько Scrum-команд разработчиков, довольно обширный стэк документов, многие из которых устарели просто потому, что в каскадной разработке писатели не успевали их обновлять. Служба поддержки завалена жалобами от пользователей: «Но у вас же так написано, почему не работает?»

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

Представьте, в требованиях ошибка или документация составлена криво. Требование уходит в разработку, программист неверно его истолкует и реализует фичу с искаженной функциональностью. Если это заметит тестировщик, отправит баг-репорт. И это ещё хороший сценарий! В реальной жизни не все баги исправляют с первого раза, а порой они попадают в прод с печальными последствиями. Как мы тестируем документацию — в продолжении.

Несколько лет назад я услышал от одного коллеги историю. Он в то время работал начальником отдела технической документации в IT компании. Дело было на собрании, посвященном знакомству с новым техническим директором. Тот, пожав моему коллеге руку и узнав о его роли, пошутил: “Документация? Так ее же не читает никто! Двадцать первый век на дворе”.

Вряд ли кому-то из нас было бы приятно оказаться на месте этого человека. Но, коллеги, положа руку на сердце, нет ли в подобном отношении нашей вины? К сожалению, я нередко сталкиваюсь с ситуациями, в которых документация, официальная или нет, не может мне помочь. А ведь ее кто-то писал, тратил время и усилия. Зачем это было сделано? И как можно сделать лучше? В этой статье я поделюсь своим видением того, как писать документацию, приносящую реальную пользу читателям.

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

Ждать долго не пришлось, при обновлении на сервере PHP c 7.2 до 7.4 - мы получили страницу с описанием ошибки, вместо документации. Ошибка найдена в библиотеке, которую мы использовали для рендеринга UI документации. ПР на гитхабе был создан быстро, но провисел в статусе open почти неделю. После этого, тикет насчет документации пошел в работу.

• Откровения трезвого инженера
• Откровения пьяного старшего инженера

Пишите хорошо

Виды документации

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

Автоматическая генерация документации — распространенный, но очень расплывчатый термин. Я понимаю под этим термином извлечение для представления в удобном виде информации, содержащейся в исходном коде и настройках документируемой программы (информационной системы).