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

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

В этой статье я начну рассказывать, как начать разрабатывать свои приложения с помощью MastermindCMS2. Я планирую создать как минимум 5 уроков, с полными объяснениями каждой функции данной технологии. Параллельно будет также YouTube канал с видео, где я также уже буду в виде стрима программировать приложения и рассказывать о своем опыте, и как я пришел к тому, что написал свой продукт для программной разработки. Обучающие видео будут на английском языке, стримы и прочая тематика будет на русском и английском языках.

Одно видео уже готово, но пока не было времени сделать пост-продакшн, анимашки всякие добавить, в общем сами понимаете, если делать продукт, то его надо делать качественно.

После небольшого вступления, давайте приступим именно к сабжу.

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

Привет, Хабр! Меня зовут Роман Блинов, я ведущий технический писатель в «Цифре» — в команде по развитию платформы ZIIoT. Этот пост будет о подходе Docs-as-code для документирования разработки ПО. Пишу с прицелом на тех читателей (то есть писателей), кто этот подход пока не пробовал и по факту имеет набор файлов в Confluence, файлы формата .docx и .pdf, на поддержку, обновление и оформление которых тратится порядка 70 % времени (а хотелось бы меньше), и 101 отговорку разработчиков, чтобы не участвовать в документировании.

Сначала расскажу, с какими проблемами сталкиваются писатели до перехода на Docs-as-code, затем опишу подход в общих чертах и в конце упомяну об основной трудности его внедрения по собственному опыту и опыту коллег.

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

При работе в разных компаниях, чаще всего встречалось раздражающее отсутствие актуальной документации или «документационная мусорная куча», где было сложно найти требуемое. Нередко проблемы были в стиле «это знал уволившийся Петя, но его не спросить». Или в наличии деталей, которые были незначимы по мнению разработчика, но которые оказывались критическим знанием «переоткрываемым» последователями (нередко и самим разработчиком, вернувшемуся к проекту). Для облегчения жизни, был сделан специальный инструмент, позволяющий держать записи по проекту прямо среди исходных текстов.

Необходимость описания персон для создания внутренних продуктов организации (автоматизация бизнес процессов) может показаться продуктовой блажью, отголоском 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 прошла успешно, хоть и не всегда гладко. Благодаря этому опыту, мы выработали несколько рекомендаций, которыми хочу поделиться.