[Подкаст] Выпуск #19. Делай проще, думай меньше

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

Читать дальше...

[Подкаст] Выпуск #18. Успешный и продуктивный

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

Читать дальше...

[Подкаст] Выпуск #17. Юзабилити документации

Жизненный цикл разработки любого продукта включает в себя этап тестирования. Более того, тестировать нужно не только функциональность, но и удобство использования (юзабилити). Документация, как продукт, не является исключением. В сегодняшнем выпуске затрагиваю такую тему, как тестирование удобства использования...

Читать дальше...

Правила хорошего тона в SQL

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

Читать дальше...

[Подкаст] Выпуск #16. Понятная инструкция

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

Читать дальше...

[Подкаст] Выпуск #15. Беседа с Иваном Чаплыгиным (Ч2)

В сегодняшнем выпуске представляю вторую часть записи беседы с профессиональным переводчиком Иваном Чаплыгиным, автором книги «Думай о смысле. Будни переводчика IT-текстов». Полезные ссылки Беседа с Иваном Чаплыгиным (Ч1)...

Читать дальше...

Лыжи и документация

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

Читать дальше...

[Подкаст] Выпуск #14. Беседа с Иваном Чаплыгиным (Ч1)

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

Читать дальше...

[Подкаст] Выпуск #13. Почему меня не понимают?

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

Читать дальше...

[Подкаст] Выпуск #12. Беседа с Ариной Балериной

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

Читать дальше...

Как написать понятную инструкцию. Опыт инженера.

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

Читать дальше...

[Подкаст] Выпуск #11. Нужен ли инженерам навык письма?

Абсолютное большинство инженеров вообще не интересуются навыком письма. Обычный ответ в этом случае: “Я только код пишу, мне этого достаточно.” И это печально, если честно. Сегодня предлагаю немного порассуждать над вопросом - нужен ли инженерам навык письма или...

Читать дальше...

Markdown шпаргалка

Пару дней назад разговорились с одним из коллег о документации. В частности, беседа зашла о подходе “документация как код” (или doc-as-code). Выяснилось, что он не знаком с языком Markdown. Было немного странно, ведь он же “компьютерщик”! В общем,...

Читать дальше...

[Подкаст] Выпуск #10. Обзор Diataxis (системный подход к созданию технической документации)

Diátaxis - подход структурирования и организации технической документации, который значительно упрощает работу с документацией как её разработчикам, так и читателям (пользователям). В сегодняшнем выпуске представлен краткий обзор данного подхода. Скачать...

Читать дальше...

[Подкаст] Выпуск #9. Визуализация данных

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

Читать дальше...

Путешествие в мир dbt начинается...

Моя небольшая история. Я работаю BI-консультантом около 14 лет. Мои основные задачи - это разработка хранилищ данных, визуализация данных и аналитика данных. Я всегда считал себя парнем из “мира данных”. Но всё-таки это не совсем верно. ...

Читать дальше...

[Подкаст] Выпуск #8. Процесс разработки технической документации (согласование и публикация)

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

Читать дальше...

Подходы к составлению инструкций

Перед тем как приступить к написанию инструкции необходимо чётко знать цель документа и его целевую аудиторию. Другими словами, зачем и для кого. Без однозначных ответов на эти вопросы начинать что-то делать категорически запрещено, да и просто глупо. Исходя...

Читать дальше...

[Подкаст] Выпуск #7. Процесс разработки технической документации (разработка)

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

Читать дальше...

Версионность документов

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

Читать дальше...

[Подкаст] Выпуск #6. Процесс разработки технической документации (подготовка)

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

Читать дальше...

[Подкаст] Выпуск #5. Документация как код

Переход российских компаний на парадигму “документация как код” в части создания и сопровождения технической документации, а также для чего нужны и как написать понятные сообщения для git-коммитов. Скачать файл ...

Читать дальше...

Интервью с Еленой Олеговной Захаровой

На днях имел огромное удовольствие пообщаться с Еленой Олеговной Захаровой, кандидатом филологических наук, доцентом учебно-научного центра “Организация и технологии высшего профессионального образования” Томского политехнического университета (ТПУ), а также автором и преподавателем курса “Техническая коммуникация”. Интервью с Еленой Олеговной...

Читать дальше...

[Подкаст] Выпуск #4. Дополнение по единому источнику правды

Небольшое дополнение к выпуску о едином источнике правды документации. Слушайте подкаст на любимых платформах: ...

Читать дальше...

Единый источник правды за пять шагов

Во втором выпуске подкаста технического коммуникатора ТЕХКОМПОД затронул тему единого источника правды и каким образом данный подход можно реализовать в Confluence. В данной заметке более наглядно представлю свою идею, которую, возможно, не совсем доступно объяснил в подкасте....

Читать дальше...

[Подкаст] Выпуск #3. Уильям Зинсер. Как писать хорошо

Отзыв на книгу Уильяма Зинсера “Как писать хорошо. Классическое руководство по созданию нехудожественных текстов”. Полезные ссылки...

Читать дальше...

[Подкаст] Выпуск #2. Единый источник правды

Как развивалась техническая документация? Что такое единый источник правды? Ответы на эти вопросы в данном выпуске подкаста. ...

Читать дальше...

[Подкаст] Выпуск #1. Знакомство

Сколько русскоязычных подкастов о технических коммуникаторах Вы слушаете? Ну, хотя бы знаете, кто такие технические коммуникаторы? Ладно, расслабьтесь. Послушайте первый выпуск и всё сразу поймёте. Скачать файл ...

Читать дальше...

Обзор книги Уильяма Зинссера 'Как писать хорошо' (с точки зрения техписателя)

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

Читать дальше...

Душа и Разум на жизненном Пути...

Некоторые мои размышления на философскую тему отношений Души и Разума… Всё-таки жизнь - удивительная штука… Работаешь на протяжении нескольких лет в какой-то сфере. Прекрасно выполняешь свою работу. Получаешь соответствующую компенсацию. И вроде бы всё хорошо. Но...

Читать дальше...

Числа в технической документации

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

Читать дальше...

Списки в технической документации

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

Читать дальше...

Таблицы в технической документации

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

Читать дальше...

Упрощённый русский

– Вы можете написать нам документацию на упрощённом русском? – Простите, что отвечаю вопросом на вопрос. Но не могли бы Вы пояснить, что Вы понимаете под фразой упрощённый русский? – Ну, как для “чайников”. Очевидно же! – Так,...

Читать дальше...

Три вопроса для анализа целевой аудитории

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

Читать дальше...

Выбор подхода к проведению исследований

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

Читать дальше...

Разработчики или техписатели?

Одними из самых распространённых типов технической документации являются инструкции или руководства. Так вот, с ними связана постоянная дилемма. Кому поручить написание инструкции - функциональному эксперту (он же разработчик или инженер) или же техническому писателю? Попробуем разобраться на типичном...

Читать дальше...

Памятка по работе с электронной почтой

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

Читать дальше...

Типы целевой аудитории

Определение целевой аудитории - одна из важнейших задач при планировании разработки технической документации. Необходимо чётко осознавать для кого и с какой целью разрабатывается тот или иной документ. Ответ на вопрос “для кого” начинается с выбора соответствующей группы или...

Читать дальше...

Три причины не сохранять документацию в PDF

Техническая документация (в основном пользовательская) в формате PDF сохраняется до сих пор во многих компаниях. Это хороший формат в том случае, если документ планируется распечатывать. Но использовать PDF в электронном виде не самый лучший вариант. Есть, как минимум,...

Читать дальше...

Упрощённый пользовательский интерфейс

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

Читать дальше...

Как пользовательская документация помогает службе поддержки?

“Пользовательская документация нужна только пользователям. Очевидно же!”. Такое мнение встречается часто, если не сказать, очень часто. У меня несколько иное мнение на этот счёт. Качественная пользовательская документация может оказать помощь сотрудникам службы поддержки. Начнём с того, что пользователи...

Читать дальше...

Форматирование для сканирования

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

Читать дальше...

Десять заповедей техписателя

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

Читать дальше...

Просто добавь… скриншот

Работая SAP-консультантом, естесственно, довольно часто приходится обращаться к SAP-документации. И всё бы ничего, ответ почти всегда находится. Но есть один неприятный момент в получении нужной информации на “хэлпе” (help.sap.com) - отсутствие скриншотов. Да, ранее я говорил, что...

Читать дальше...

Скринкасты vs старый-добрый текст

Ранее возникала мысль оставить небольшую заметку на эту тему, но думал, что не очень она интересная. Однако произошедший на днях случай буквально заставил меня “взяться за перо”. Дело было так. Предложили мне ознакомиться с имеющимся материалом...

Читать дальше...

Базовый пакет тестирования документации

В предыдущей заметке был затронут вопрос тестирования документации, точнее был дан краткий ответ на вопрос “Зачем тестировать документацию?”. Здесь же постараюсь ответить на следующий часто возникающий вопрос - “Кто должен тестировать документацию?”. В первую очередь, конечно же данная...

Читать дальше...

Баги документации

“Зачем тестировать документацию?”. Этот вопрос с удивлением задают многие разработчики, тестировщики, руководители проектов. “Это же не программный код… Багов там быть не может. В общем, чепуха какая-то… Главное, чтобы хоть какая-то документация была готова к релизу”, - продолжают...

Читать дальше...

Техписатель и техзадание

Давно хотел написать свои мысли по этому поводу, но как-то всё руки “не доходили”. А тут, можно сказать, ситуация сама нарисовалась. Поэтому родилась эта небольшая заметка про техписателей и технические задания (ТЗ). На днях произошел примерно такой случай....

Читать дальше...

Повелительное наклонение

Как правильно формулировать пошаговые действия пользователя в документации? После ознакомления с очередным обучающим материалом, подготовленным одним из моих коллег, решил перенести некоторые свои мысли “на бумагу”. Хотя этот конкретный случай касается обучающего видеоролика, тем не менее заметка в...

Читать дальше...

Три правила сокращений

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

Читать дальше...

Место или действие?

Какой способ описания пошагового действия применять при оформлении руководств и/или инструкций - начинать с выполняемого действия или области интерфейса (места), где это действие выполняется? Приведу свои мысли по этому поводу. Руководства к оформлению технической документации ИТ-индустрии излагают,...

Читать дальше...

Документация как код

“Документация как код” (“docs as code” или “docs like code”) - подход в создании и поддержке технической документации с использованием систем, инструментов, процессов, которые применяются в разработке программного кода. Признаки подхода “документация как код”: Ведение документации...

Читать дальше...

Формула ТУПО в оформлении технической документации

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

Читать дальше...

Рабочий процесс технического писателя. Согласование

После выполнения шагов “Подготовка” и “Разработка” наступает черёд согласования документации. Согласование является итерационным (повторяющимся) процессом. И невозможно с точностью спрогнозировать количество итераций. С большой долей вероятности можно сказать, что минимальное их количество равно двум. Потому как...

Читать дальше...

Рабочий процесс технического писателя. Разработка

После выполнения шага “Подготовка” осуществляется переход к разработке документации. Разработка так же может быть разделена на более детальные шаги: Структурирование. Написание. Вычитка. Структурирование Полученная при проведении...

Читать дальше...

Рабочий процесс технического писателя. Подготовка

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

Читать дальше...

Рабочий процесс технического писателя

В основе любой профессии находится набор определённых процессов. Согласно официальному определению ГОСТ Р ИСО 9000-2015 (Национальный стандарт Российской Федерации. Системы менеджмента качества) под процессом понимается совокупность взаимосвязанных и (или) взаимодействующих видов деятельности, использующих входы для получения намеченного результата....

Читать дальше...

Гуманитарии или технари?

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

Читать дальше...

Какие требования предъявляются к техническим писателям?

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

Читать дальше...

Сферы деятельности технических писателей

В каких сферах трудятся технические писатели? Этот вопрос часто задают люди, которые впервые сталкиваются с профессией “техписатель” и начинают искать более подробную информацию. Итак, попробую ответить на данный вопрос. Технические писатели заняты во многих отраслях и...

Читать дальше...

Есть такая профессия - документацию разрабатывать

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

Читать дальше...