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

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

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

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

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

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

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

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

Как мы оценивали качество документации - 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

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

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

KnowledgeConf: Настало время делиться знаниями - 1

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

KnowledgeConf 2019, профессиональная конференция по управлению знаниями в IT компаниях пройдет 26 апреля 2019 на площадке ИнфоПространство в центре Москвы.

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

Почему строить базу знаний компании на основе mediawiki — недурная затея - 1

В последнее время Confluence и sharepoint стали почти безраздельно править на рынке баз знаний. Системы отличные, не спорю, но лично мне не хватает их гибкости да и в целом как-то не срослось: вики-возможности sharepoint остались где-то на уровне 2005 года (про работу с офисными документами молчу, с ними все гуд), а Confluence в силу своих особенностей с ростом числа статей неумолимо превращался в свалку, в которой невозможно найти что-либо нужное (но, может, проблема была во мне).

Не умаляя достоинства этих систем, хотелось бы рассказать о том, какие возможности есть у Mediawiki в роли корпоративной базы знаний. Само собой, mediawiki подойдет не всем — в ней нет модной интеграции с jira/tfs/etc, перенос документов с картинками из пакета Microsoft Office доставляет кучу неудобств, да и сама она написана на PHP, что в последнее время служит отпугивающим фактором для некоторых айтишников. Тем не менее, платформа живее всех живых и над ее развитием работает изрядное количество людей, коль скоро на ней базируется семейство проектов фонда Викимедиа.
Читать полностью »