Рубрика «документация»

Семь «абсолютных истин» джуниора, от которых пришлось отучиваться - 1

Скоро наступит десятый год, как я профессионально занимаюсь программированием. Десять лет! И кроме формальной работы, почти две трети своей жизни я что-то создавала в интернете. С трудом вспоминаю годы, когда я не знала HTML: даже странно, если подумать об этом. Некоторые дети учатся музыке или балету, а я вместо этого создавала волшебные миры, кодируя в своей детской.

Размышляя об этом первом десятилетии регулярного получения денег за ввод странных символов в терминал, хотелось бы поделиться некоторыми наблюдениями, как изменилось моё мышление за годы работы.
Читать полностью »

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

Как оживить документацию? - 1

На web-проектах Альфа-Банка используется фреймворк для автоматизации тестирования Akita, который использует для BDD-сценарии. К настоящему моменту фреймворк набрал большую популярность благодаря низкому порогу входа, удобству использования и возможности тестировать верстку. Но мы решили пойти дальше — на основе описанных тестовых сценариев формировать документацию, тем самым сильно сокращая время которое аналитики тратят на на извечную проблему актуализации документации.

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

  • скриншоты;
  • значения переменных (config File, учетные записи пользователей и т.д.);
  • статусы и параметры запросов.

Мы посмотрели на наш существующий плагин, который был, по сути, статическим анализатором и формировал документацию на основе описанных в .feature-файлах сценариев. Решили добавить динамики, и для того, чтобы не городить плагин над плагином, приняли решение написать свой собственный.
Читать полностью »

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

Рассказывает Юрий Никулин, руководитель службы разработки технической документации.

Для начала давайте определим, что такое производительность. В классическом понимании, это время на производство единицы продукции или количество продукции, произведенное в единицу времени.

Например, это количество произведенных телефонов за месяц или количество времени на производство тысячи телефонов. Возникает вопрос, как измерять интеллектуальный труд, которым занимается наш отдел.

Читать полностью »

Привет! Меня зовут Леша, я системный аналитик одной из продуктовых команд Альфа-Банка. Сейчас я занимаюсь развитием нового интернет-банка для юридических лиц и индивидуальных предпринимателей.

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

Как мы оценивали качество документации - 1

При этом игнорировать документацию нельзя по очевидным причинам. И чтобы упростить нам жизнь, мы решили провести оценку качества документации. Как именно мы это делали и к каким выводам пришли — под катом.
Читать полностью »

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

Как «снести» вашу документацию и начать жить - 1

Под катом перевод доклада Александры Уайт, технического писателя из компании Google, на конференции Write the Docs Prague 2018. А уже через неделю 26 апреля 2019 Александра выступит на нашей конференции KnowledgeConf с докладом «How to create compelling multimedia documentation». Александра расскажет, как встроить мультимедиа форматы (видео, аудио, gif) в процесс создания артефактов и упаковки знаний, когда мультимедиа форматы подойдут лучше всего, а когда не будут работать, как измерять эффективность мультимедиа артефактов и преодолевать их ограничения.
Читать полностью »

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

Дайджест интересных материалов для мобильного разработчика #292 (25 марта — 31 марта) - 1Читать полностью »

KnowledgeConf: нам нужно серьезно поговорить о докладах - 1

В первый день весны (или пятый месяц зимы, кому как) закончилась подача заявок на KnowledgeConf — конференцию про управление знаниями в IT компаниях. Признаться, итоги Call for Papers превзошли все ожидания. Да, мы понимали, что тема актуальная, видели это на других конференциях и митапах, но что у нее откроется столько новых граней и ракурсов — и подумать не могли.

Всего Программный комитет получил 83 заявки на доклады. Как и ожидалось, в последние сутки прилетело больше двух десятков. Мы в Программном комитете все пытались понять, почему так происходит. А потом один из нас признался, что и сам часто откладывал до последнего, потому что ему и в голову не приходило, что в момент окончания подачи заявок работа над многими докладами: созвоны, обсуждение, получение обратной связи, идёт уже месяц-два, более того, большая часть программы может быть уже заполнена.

Мы понимаем, что с точки зрения тех, кто подает заявки, это выглядит примерно как на картинке ниже, но это не так.

KnowledgeConf: нам нужно серьезно поговорить о докладах - 2

Извне кажется, что после дедлайна все только начинается, что мы Программным комитетом только собрались и начинаем разгребать заявки, поэтому взять и обработать еще одну не трудно. Но на самом деле мы вовсе не сидели сложа руки. Но это лишь лирическое отступление, чтобы поделиться тем, как выглядит Call for Papers изнутри ПК, вернемся к докладам.

83 — это почти 3,5 доклада на одно место в программе, и теперь нам предстоит отобрать лучшие и довести их до состояния, близкого к идеалу.
Читать полностью »

Циклы технологий управления знаний по Гартнеру на примере поданных докладов на KnowledgeConf - 1

В первый день весны (или пятый месяц зимы, кому как) закончилась подача заявок на KnowledgeConf — конференцию про управление знаниями в IT компаниях. Признаться, итоги Call for Papers превзошли все ожидания. Да, мы понимали, что тема актуальная, видели это на других конференциях и митапах, но что у нее откроется столько новых граней и ракурсов — и подумать не могли.

Всего Программный комитет получил 83 заявки на доклады. Как и ожидалось, в последние сутки прилетело больше двух десятков. Мы в Программном комитете все пытались понять, почему так происходит. А потом один из нас признался, что и сам часто откладывал до последнего, потому что ему и в голову не приходило, что в момент окончания подачи заявок работа над многими докладами: созвоны, обсуждение, получение обратной связи, идёт уже месяц-два, более того, большая часть программы может быть уже заполнена.

Мы понимаем, что с точки зрения тех, кто подает заявки, это выглядит примерно как на картинке ниже, но это не так.

Циклы технологий управления знаний по Гартнеру на примере поданных докладов на KnowledgeConf - 2

Извне кажется, что после дедлайна все только начинается, что мы Программным комитетом только собрались и начинаем разгребать заявки, поэтому взять и обработать еще одну не трудно. Но на самом деле мы вовсе не сидели сложа руки. Но это лишь лирическое отступление, чтобы поделиться тем, как выглядит Call for Papers изнутри ПК, вернемся к докладам.

83 — это почти 3,5 доклада на одно место в программе, и теперь нам предстоит отобрать лучшие и довести их до состояния, близкого к идеалу.
Читать полностью »

Рассказывает Светлана Каюшина, руководитель отдела документирования и локализации.

Наш отдел документирования прошел несколько этапов развития. Сначала был технический писатель, выполнявший задачи отдельного заказчика. Потом образовалась группа технических писателей, которая решала ограниченный набор задач. Сейчас у нас большой производственный отдел — он полностью удовлетворяет потребности компании в документировании.

Читать полностью »

image

Документация к софту — это просто набор статей. Но даже они могут вывести из себя. Сначала долго ищешь нужную инструкцию. Потом разбираешься в малопонятном тексте. Делаешь как написано, а проблема не решается. Ищешь другую статью, нервничаешь… Через час плюёшь на всё и уходишь. Так работает плохая документация. Что делает её такой, и как это исправить — читайте под катом.
Читать полностью »