И начать делать полезную документацию

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

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

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

Уровень: начинающим, продолжающим, ленивым

Что, опять? Но зачем!?

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

Искусство организации рабочего времени (time-management) последнее время обретает всё большую популярность и если раньше это в основном относилось к менеджерам различного уровня, то теперь накопленные знания начинают применяться и в других областях деятельности компании.

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

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



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

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



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

      Сталкивались ли вы когда нибудь с долгим поиском документации к используемой библиотеке или пакету? Я считаю странным, что исходный код не распространяется с пользовательской документацией. Ведь она такая же важная часть кода, как тесты или зависимости. Без хорошей пользовательской документации мы можем «убить» уйму времени на анализ кода и комментариев. Так почему бы не хранить пользовательскую документацию вместе с исходными кодами программы? Речь не о DocBlock и генерацию документации по API проекта, я говорю именно о пользовательской документации, которую мы так любим за последовательное повествование и множество примеров.

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

Многим статья может показаться «капитанской». Если вы почувствуете на своих щеках соленые брызги и услышите шум волн, немедленно прекратите чтение!

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

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

Вступление…

Решился продолжить статьи
«История одной инфраструктуры. Решения MS. Часть 1»
«История одной инфраструктуры. Решения MS. Часть 2»
«История одной инфраструктуры. Решения MS. Часть 3»
и более подробно рассмотреть вопрос создания документации информационной системы (ИС) предприятия. Сразу оговорюсь, что не претендую на истину, всего лишь, мой подход и мои соображения по данному вопросу. Надеюсь, что смогу помочь начинающим разработчикам документации в этом нелегком деле.

“Что за дело? Это многих славных путь.”
Н.А. Некрасов

Всем привет!

Меня зовут Карина, и я “совместитель” — совмещаю учёбу в магистратуре и работу технического писателя в Veeam Software. О том, как у меня это вышло, я и хочу рассказать. Заодно кто-то узнает, как можно прийти в эту профессию, и какие я вижу для себя плюсы и минусы в работе во время учебы.

Я работаю в Veeam без году неделю полгода с небольшим, и это были самые насыщенные полгода моей жизни. Я пишу техническую документацию (и учусь её писать) — сейчас я занимаюсь руководством по Veeam ONE Reporter (вот оно) и гайдами по Veeam Availability Console (про нее была статья на Хабре) для конечных пользователей и реселлеров. Еще я из тех, кому сложно парой слов ответить на вопрос «Откуда ты приехала?». Вопрос «Как ты проводишь свободное время?» тоже не из простых.


Взгляд работающего студента, когда ему жалуются на недостаток свободного времени

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

Советы по грамотному написанию технической документации для пользователей.
Часть 1

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

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

Как бы ни старался UX-дизайнер, не сможет человек с улицы разобраться в интерфейсе управления космическим кораблём без подсказки. И даже не с улицы. Просто потому, что ракета большая и настроек много.

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

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

Хотя второй по счету митап Write the Docs Moscow состоялся уже месяц назад, опубликовать отчет и краткие конспекты докладов никогда не поздно. Мы успели обсудить ну практически все: от документирования RESTful API до профессиональных траекторий техписателя.

Митап, кстати собрал не только «техписательское гетто», но и широкий круг других специалистов, кто так или иначе работает испытывает боль с документацией на проекте: тимлиды, аналитики, тестировщики и даже один технический директор.

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

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

При работе над кейсом проекта Designet я поймал себя на том, что считаю термины «фронтенд», «клиентская сторона» и «интерфейс» синонимами. Чтобы расставить все точки над i и больше их не путать, я написал эту памятку. Надеюсь, что она поможет не только мне, но и коллегам — редакторам, копирайтерам, техническим журналистам, маркетологам, менеджерам проектов и всем, кто не имеет прямого отношения к программированию.

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

При всех своих масштабах и линейке более чем из 60 настраиваемых решений «Лаборатория Касперского» действует прежде всего в интересах пользователя. Важная часть нашей работы — тексты: мы общаемся с пользователями наших продуктов с помощью элементов интерфейса и документации.



Год назад в «Лаборатории Касперского» прошла первая встреча «ProКонтент» для технических писателей, редакторов, переводчиков и локализаторов. 16 марта 2017 года мы вновь приглашаем к себе всех желающих, чтобы раскрыть свои секреты и поговорить о том, что нас объединяет. О контенте.

В прошлый раз мы говорили о разнице между login и log in. В продолжение темы — ещё несколько нюансов, о которых вы просили рассказать в комментариях.

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

Привет, Хабровчане!
Что вы думаете про нашу техническую документацию и локализации продуктов, если вам доводилось с ними сталкиваться? И читаете ли вы документацию вообще?
В свою очередь, мы хотим рассказать вам, как ЛК удается делать так, чтобы и русский, и англичанин, и китаец одинаково легко обращались с нашими программами. Больше всех об этом знает руководитель отдела локализации и разработки технической документации Татьяна Родионова.

― Татьяна, насколько это вообще объемная работа, как много сотрудников числится в вашем отделе?

― Сейчас в отделе работают 48 человек. По функциям все они делятся на 4 группы. Группа технического документирования разрабатывает материалы, которые помогают пользователю разобраться в программе. Это тексты графического интерфейса продуктов, справка, интегрированная в продукт, а также сопроводительные документы, такие как «Руководство пользователя». Тексты пишут технические писатели.
Локализацией текстов на языки занимаются переводчики и инженеры группы локализации. Сегодня мы локализуем наши продукты на 33 языка. Основные языки ― русский, английский, немецкий, французский и для некоторых продуктов ― китайский. Понятно, что локализовать продукт на 33 языка силами только штатных сотрудников невозможно. В помощь мы привлекаем переводческие агентства и носителей языков по всему миру.