Тенденция в мире данных
Мир данных уже не тот. Как и всё вокруг нас меняется с немыслимой скоростью, мир данных очень сильно изменился за последние несколько лет. Если 10–15 лет назад тенденция была такова, что от специалиста требовалось наличие широкого спектра навыков,...
[Подкаст] Выпуск #19. Делай проще, думай меньше
Делай проще, чтобы поняли, да и сам думай меньше, задачу закрыть надо… В сегодняшнем выпуске поделюсь своими мыслями о тенденции упрощения всего и вся в нашей жизни. И какое участие принимаем в этом процессе мы - инженеры, технические...
[Подкаст] Выпуск #18. Успешный и продуктивный
Успешный и продуктивный инженер, успешный и продуктивный технический писатель, успешный и продуктивный переводчик и т.д. Многие из нас хотят быть успешными и продуктивными. В сегодняшнем выпуске я поделюсь своими размышлениями о продуктивности и как она может помочь нам...
[Подкаст] Выпуск #17. Юзабилити документации
Жизненный цикл разработки любого продукта включает в себя этап тестирования. Более того, тестировать нужно не только функциональность, но и удобство использования (юзабилити). Документация, как продукт, не является исключением. В сегодняшнем выпуске затрагиваю такую тему, как тестирование удобства использования...
Правила хорошего тона в SQL
Инженеры не любят писать - известный факт. Это относится не только к документации, различным отчетам, электронным письмам, комментариям к своему коду, но даже и наименованиям сущностей их атрибутов в этом самом коде. Вот на последнем остановлюсь подробнее. Многие...
[Подкаст] Выпуск #16. Понятная инструкция
В процессе выполнения одной из основных задач на работе в прошлом году довелось изучить различное программное обеспечение по разработке хранилищ данных, а также документацию к нему. Так плохо написанной документации - в частности, инструкции для администраторов и пользователей...
[Подкаст] Выпуск #15. Беседа с Иваном Чаплыгиным (Ч2)
В сегодняшнем выпуске представляю вторую часть записи беседы с профессиональным переводчиком Иваном Чаплыгиным, автором книги «Думай о смысле. Будни переводчика IT-текстов». Полезные ссылки Беседа с Иваном Чаплыгиным (Ч1)...
Лыжи и документация
Люблю беговые лыжи. Как только появляется возможность, берём с детьми лыжи и мчимся навстречу приключениям. Так случилось и сегодня. Прекрасная и столь редкая для Москвы погода - небольшой морозец, сухой и воздушный снег, ясное небо и яркое солнце!...
[Подкаст] Выпуск #14. Беседа с Иваном Чаплыгиным (Ч1)
Не устану повторять, что технические коммуникаторы - это не только техническими писатели, как многие привыкли думать. К техническим коммуникаторам можно отнести длинный перечень профессий. Иногда сложно сходу сказать, относится ли какая-то профессия к техническим коммуникаторам. Вот на примере...
[Подкаст] Выпуск #13. Почему меня не понимают?
В жизни каждого из нас, как в профессиональной сфере, так и в быту, очень часто встречаются ситуации, когда собеседники не понимают нас. В эти моменты мы задаёмся примерно такими вопросами: Почему меня не понимают? Как объяснять так, чтобы...
[Подкаст] Выпуск #12. Беседа с Ариной Балериной
Уже не раз говорил, что пытаюсь вести просветительскую деятельность по развитию культуры осознанной работы с написанием документации у инженеров. Не всегда мои слова звучат убедительно, так как я не являюсь экспертом в данном вопросе. Но под Новый год...
Как написать понятную инструкцию. Опыт инженера.
Инженеры разучились писать инструкции. Хотя умели прекрасно это делать. И проблема эта, по всей видимости, глобальная. Такое мнение родилось у меня не на пустом месте. Тому есть две причины. Первой причиной является то, что некоторым моим чуть менее...
[Подкаст] Выпуск #11. Нужен ли инженерам навык письма?
Абсолютное большинство инженеров вообще не интересуются навыком письма. Обычный ответ в этом случае: “Я только код пишу, мне этого достаточно.” И это печально, если честно. Сегодня предлагаю немного порассуждать над вопросом - нужен ли инженерам навык письма или...
Markdown шпаргалка
Пару дней назад разговорились с одним из коллег о документации. В частности, беседа зашла о подходе “документация как код” (или doc-as-code). Выяснилось, что он не знаком с языком Markdown. Было немного странно, ведь он же “компьютерщик”! В общем,...
[Подкаст] Выпуск #10. Обзор Diataxis (системный подход к созданию технической документации)
Diátaxis - подход структурирования и организации технической документации, который значительно упрощает работу с документацией как её разработчикам, так и читателям (пользователям). В сегодняшнем выпуске представлен краткий обзор данного подхода. Скачать...
[Подкаст] Выпуск #9. Визуализация данных
Технические коммуникаторы - это не только техписатели, как многие привыкли считать, это достаточно широкий диапазон профессий. Среди этих профессий присутствуют также специалисты по визуализации данных. В сегодняшнем выпуске рассмотрим визуализацию данных, как вид техкоммуникации. Моя небольшая история. Я работаю BI-консультантом около 14 лет. Мои основные задачи - это разработка хранилищ данных, визуализация данных и аналитика данных. Я всегда считал себя парнем из “мира данных”. Но всё-таки это не совсем верно. ... В основе любой деятельности лежит набор определенных процессов. Разработка технической документации не является исключением. В сегодняшнем выпуске о третьем и четвертом этапах процесса создания документации. Скачать файл ... Перед тем как приступить к написанию инструкции необходимо чётко знать цель документа и его целевую аудиторию. Другими словами, зачем и для кого. Без однозначных ответов на эти вопросы начинать что-то делать категорически запрещено, да и просто глупо. Исходя... В основе любой деятельности лежит набор определенных процессов. Разработка технической документации не является исключением. В сегодняшнем выпуске о втором этапе процесса создания документации. ... Некоторое время назад столкнулся с тем, что один из коллег, после внесения правок в документ, не совсем корректно присвоил этому документу очередной номер версии. На свой вопрос, каким образом он определил номер версии, я получил довольно путанный ответ.... В основе любой деятельности лежит набор определенных процессов. Разработка технической документации не является исключением. В сегодняшнем выпуске о первом этапе процесса создания документации. Переход российских компаний на парадигму “документация как код” в части создания и сопровождения технической документации, а также для чего нужны и как написать понятные сообщения для git-коммитов. Скачать файл ... На днях имел огромное удовольствие пообщаться с Еленой Олеговной Захаровой, кандидатом филологических наук, доцентом учебно-научного центра “Организация и технологии высшего профессионального образования” Томского политехнического университета (ТПУ), а также автором и преподавателем курса “Техническая коммуникация”. Интервью с Еленой Олеговной... Небольшое дополнение к выпуску о едином источнике правды документации. Слушайте подкаст на любимых платформах: ... Во втором выпуске подкаста технического коммуникатора ТЕХКОМПОД затронул тему единого источника правды и каким образом данный подход можно реализовать в Confluence. В данной заметке более наглядно представлю свою идею, которую, возможно, не совсем доступно объяснил в подкасте.... Отзыв на книгу Уильяма Зинсера “Как писать хорошо. Классическое руководство по созданию нехудожественных текстов”. Полезные ссылки... Как развивалась техническая документация? Что такое единый источник правды? Ответы на эти вопросы в данном выпуске подкаста. ... Сколько русскоязычных подкастов о технических коммуникаторах Вы слушаете? Ну, хотя бы знаете, кто такие технические коммуникаторы? Ладно, расслабьтесь. Послушайте первый выпуск и всё сразу поймёте. Скачать файл ... Каждому профессионалу необходимо постоянно развивать и совершенствовать навыки, чтобы повышать свою ценность на рынке. Это касатеся и технических писателей. Технические писатели должны совершенствоваться не только в плане технологий, о которых пишут. Вторая часть в названии профессии указывает, что... Некоторые мои размышления на философскую тему отношений Души и Разума… Всё-таки жизнь - удивительная штука… Работаешь на протяжении нескольких лет в какой-то сфере. Прекрасно выполняешь свою работу. Получаешь соответствующую компенсацию. И вроде бы всё хорошо. Но... Продолжаю небольшую серию про принципы и правила оформления и структурирования материала в технической документаци. В предыдущих заметках прошёлся по таблицам и спискам. Сегодняшняя небольшая, но интересная (по крайней мере, для меня) тема - правила написания чисел... В предыдущей заметке шла речь о таблицах. В текущей же заметке решил продолжить тему оформления текста документации. Итак, применение списков в технической документации. Списки являются полезным и эффективным инструментом организации материала документа, выделения важных идей, упрощения длинных... На днях проверял домашнюю работу сына по биологии. Перед ним стояла задача составить конспект по заданной теме. К слову, мальчик учится в пятом классе. Ранее мы с ним разбирали несколько способов составления конспекта. Одним из наиболее эффективных из... – Вы можете написать нам документацию на упрощённом русском? – Простите, что отвечаю вопросом на вопрос. Но не могли бы Вы пояснить, что Вы понимаете под фразой упрощённый русский? – Ну, как для “чайников”. Очевидно же! – Так,... Анализ целевой аудитории является неотъемлемым и одним из самых важных шагов исследований в рамках процесса разработки технической документации. Чем больше информации (разумеется, именно релевантной, относящейся к делу) имеется о пользователях продукта, тем лучше и проще можно донести нужную... Проведение исследований - одна из основных задач технических писателей. Исследование является одним из первых и, пожалуй, одним из самых важных шагов в процессе разработки технической документации. Но необходимо тщательно собраться. У техписателя на момент начала исследования должно быть... Одними из самых распространённых типов технической документации являются инструкции или руководства. Так вот, с ними связана постоянная дилемма. Кому поручить написание инструкции - функциональному эксперту (он же разработчик или инженер) или же техническому писателю? Попробуем разобраться на типичном... Электронная почта до сих пор является одним из основных корпоративных инструментов коммуникации. Но к большому несчастью, этим инструментом перестали пользоваться правильно. К нему относятся, словно к мессенджеру, то есть как к программе мгновенного обмена сообщениями. Например, отправляется большое... Определение целевой аудитории - одна из важнейших задач при планировании разработки технической документации. Необходимо чётко осознавать для кого и с какой целью разрабатывается тот или иной документ. Ответ на вопрос “для кого” начинается с выбора соответствующей группы или... Техническая документация (в основном пользовательская) в формате PDF сохраняется до сих пор во многих компаниях. Это хороший формат в том случае, если документ планируется распечатывать. Но использовать PDF в электронном виде не самый лучший вариант. Есть, как минимум,... Скриншоты являются неотъемлемой частью технической документации. Особенно это касается различных инструкций и руководств (об этом уже была одна из предыдущих заметок). Казалось бы, какие тут могут быть проблемы и как их можно устранить (если уж они возникают)?... “Пользовательская документация нужна только пользователям. Очевидно же!”. Такое мнение встречается часто, если не сказать, очень часто. У меня несколько иное мнение на этот счёт. Качественная пользовательская документация может оказать помощь сотрудникам службы поддержки. Начнём с того, что пользователи... Появление и развитие интернета оказало огромное влияние на жизнь человечества. Не буду здесь уходить в дебри, эта тема уже столько раз обсуждалась, что перестала быть интересной кому-либо. Напомню лишь, что вместе с положительными приобретениями от интернета, человечество получило... В каждой профессии есть свои официальные, а также негласные правила. Технические писатели не являются исключением. Предлагаю свой (не лично мной придуманный, но подчерпнутый из различных источников и постоянно применяемый в работе) небольшой список таких негласных правил или, так... Работая SAP-консультантом, естесственно, довольно часто приходится обращаться к SAP-документации. И всё бы ничего, ответ почти всегда находится. Но есть один неприятный момент в получении нужной информации на “хэлпе” (help.sap.com) - отсутствие скриншотов. Да, ранее я говорил, что... Ранее возникала мысль оставить небольшую заметку на эту тему, но думал, что не очень она интересная. Однако произошедший на днях случай буквально заставил меня “взяться за перо”. Дело было так. Предложили мне ознакомиться с имеющимся материалом... В предыдущей заметке был затронут вопрос тестирования документации, точнее был дан краткий ответ на вопрос “Зачем тестировать документацию?”. Здесь же постараюсь ответить на следующий часто возникающий вопрос - “Кто должен тестировать документацию?”. В первую очередь, конечно же данная... “Зачем тестировать документацию?”. Этот вопрос с удивлением задают многие разработчики, тестировщики, руководители проектов. “Это же не программный код… Багов там быть не может. В общем, чепуха какая-то… Главное, чтобы хоть какая-то документация была готова к релизу”, - продолжают... Давно хотел написать свои мысли по этому поводу, но как-то всё руки “не доходили”. А тут, можно сказать, ситуация сама нарисовалась. Поэтому родилась эта небольшая заметка про техписателей и технические задания (ТЗ). На днях произошел примерно такой случай.... Как правильно формулировать пошаговые действия пользователя в документации? После ознакомления с очередным обучающим материалом, подготовленным одним из моих коллег, решил перенести некоторые свои мысли “на бумагу”. Хотя этот конкретный случай касается обучающего видеоролика, тем не менее заметка в... Небольшая заметка про использование аббревиатур или сокращений в технической документации. В каждой сфере деятельности используется множество сокращений, полученных по первым буквам словосочетаний, или иначе аббревиатуры. Информационные технологии (ИТ) не исключение. Возможно, даже лидер по этому показателю. Но есть... Какой способ описания пошагового действия применять при оформлении руководств и/или инструкций - начинать с выполняемого действия или области интерфейса (места), где это действие выполняется? Приведу свои мысли по этому поводу. Руководства к оформлению технической документации ИТ-индустрии излагают,... “Документация как код” (“docs as code” или “docs like code”) - подход в создании и поддержке технической документации с использованием систем, инструментов, процессов, которые применяются в разработке программного кода. Признаки подхода “документация как код”: Ведение документации... Подходы к оформлению технической документации подробно изложены в соответсвующих руководствах/документах лидеров ИТ-индустрии. Изобретать велосипед здесь излишне. Настоятельно рекомендую ознакомиться с этими документами (в конце заметки перечислены некоторые из них). Здесь же привожу основные моменты оформления (или, как я... После выполнения шагов “Подготовка” и “Разработка” наступает черёд согласования документации. Согласование является итерационным (повторяющимся) процессом. И невозможно с точностью спрогнозировать количество итераций. С большой долей вероятности можно сказать, что минимальное их количество равно двум. Потому как... После выполнения шага “Подготовка” осуществляется переход к разработке документации. Разработка так же может быть разделена на более детальные шаги: Структурирование. Написание. Вычитка. Структурирование Полученная при проведении... Подготовка является, пожалуй, самым важным шагом в рабочем процессе технического писателя. Насколько качественно будут выполнены подготовительные работы, настолько качественно будет выполнена целевая задача по разработке документации. В свою очередь, подготовка может быть разделена на более детальные... В основе любой профессии находится набор определённых процессов. Согласно официальному определению ГОСТ Р ИСО 9000-2015 (Национальный стандарт Российской Федерации. Системы менеджмента качества) под процессом понимается совокупность взаимосвязанных и (или) взаимодействующих видов деятельности, использующих входы для получения намеченного результата.... Какая стартовая позиция для начала карьеры лучше - гуманитарий, проявляющий интерес к технологиям, или технарь, умеющий легко, просто и доступно излагать свои мысли? Совсем небольшая заметка с попыткой ответа на поставленный вопрос. К сожалению, однозначного ответа... Профессия “Технический писатель” в России официально существует с 2014 года, когда был принят соответствующи профессиональный стандарт. В этом документе приведены требования к образованию, трудовые функции, необходимые знания и умения в зависимости от уровня квалификации. Как говорится, лучше один... В каких сферах трудятся технические писатели? Этот вопрос часто задают люди, которые впервые сталкиваются с профессией “техписатель” и начинают искать более подробную информацию. Итак, попробую ответить на данный вопрос. Технические писатели заняты во многих отраслях и... Развитие технологий привело и продолжает приводить к появлению огромного числа всевозможных устройств и систем, с которыми мы сталкиваемся повсеместно и ежедневно. Несмотря на то, что общая тенденция большинства технологий направлена на значительное упрощение процессов взаимодействия человека со сложными... Путешествие в мир dbt начинается...
[Подкаст] Выпуск #8. Процесс разработки технической документации (согласование и публикация)
Подходы к составлению инструкций
[Подкаст] Выпуск #7. Процесс разработки технической документации (разработка)
Версионность документов
[Подкаст] Выпуск #6. Процесс разработки технической документации (подготовка)
[Подкаст] Выпуск #5. Документация как код
Интервью с Еленой Олеговной Захаровой
[Подкаст] Выпуск #4. Дополнение по единому источнику правды
Единый источник правды за пять шагов
[Подкаст] Выпуск #3. Уильям Зинсер. Как писать хорошо
[Подкаст] Выпуск #2. Единый источник правды
[Подкаст] Выпуск #1. Знакомство
Обзор книги Уильяма Зинссера 'Как писать хорошо' (с точки зрения техписателя)
Душа и Разум на жизненном Пути...
Числа в технической документации
Списки в технической документации
Таблицы в технической документации
Упрощённый русский
Три вопроса для анализа целевой аудитории
Выбор подхода к проведению исследований
Разработчики или техписатели?
Памятка по работе с электронной почтой
Типы целевой аудитории
Три причины не сохранять документацию в PDF
Упрощённый пользовательский интерфейс
Как пользовательская документация помогает службе поддержки?
Форматирование для сканирования
Десять заповедей техписателя
Просто добавь… скриншот
Скринкасты vs старый-добрый текст
Базовый пакет тестирования документации
Баги документации
Техписатель и техзадание
Повелительное наклонение
Три правила сокращений
Место или действие?
Документация как код
Формула ТУПО в оформлении технической документации
Рабочий процесс технического писателя. Согласование
Рабочий процесс технического писателя. Разработка
Рабочий процесс технического писателя. Подготовка
Рабочий процесс технического писателя
Гуманитарии или технари?
Какие требования предъявляются к техническим писателям?
Сферы деятельности технических писателей
Есть такая профессия - документацию разрабатывать