Всё для технического документирования
+7 (925) 328-76-00
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Новости о техническом писательстве

Ключ к написанию хорошей документации: тестирование инструкций

25.09.2017

Всем нам попадались инструкции, в которых было или сложно найти то, что нужно, или была куча непонятных терминов, или даже отсутствовали какие-то шаги в последовательности действий. А некоторые из нас и сами писали такие инструкции ? Чтобы этого избежать, необходимо проводить тестирование документации как неотъемлемой части разрабатываемых продуктов. Статья посвящена организации тестирования документации на предприятии и проблемам, которые при этом возникают. Автор: Том Джонсон, технический писатель из США.

Нет времени писать и/или тестировать инструкции? Заказать разработку инструкции в компании «ПроТекст» — лучшее решение!

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

О тестировании

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

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



Элементарно, мой дорогой Ватсон: Редактор как Детектив

23.08.2017

Представляем вашему вниманию статью о работе редактора. Автор: Джефф Харт, сейчас работающий на фрилансе научным редактором, а ранее в таких организациях как IBM, Лесничество Канады и Канадский лесной институт.

Нужен редактор? Их есть у нас! Выполним редакторскую и корректорскую правку Ваших текстов в сжатые сроки.

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

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

  • мотив
  • благоприятная возможность
  • средства

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



Как улучшить написание записей для блога и технических статей

19.11.2015

00Диа Ривз, редактор из Microsoft, делится своими советами с писателями, которые ведут технические блоги и пишут публикации для технических изданий. Советы основаны на её восприятии современных тенденций в ИТ-области, и они будут полезны широкому кругу документаторов.


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

Давайте послушаем… группа вздыхает…

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



Как вычитать текст и не заставить всех себя ненавидеть

29.08.2014

Studio shot of young student with books and computerКак будучи редактором не стать кругом виноватым? Сегодня с нами делится своими наблюдениями и опытом переводчик и редактор компании «ПроТекст» Оксана Шолохова.


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

Во-первых, разберёмся с авторами. Их можно понять – не очень приятно, когда предложение, над которым ты бился минут сорок, безжалостно вычёркивают. Но помните – работа писателя завершена, теперь вся власть перешла к вам (хотя задирать нос и устраивать редакторский произвол тоже не стоит). Что же делать, чтобы и работа была выполнена качественно, и отношения с коллегами не испортились? Читать дальше…



Встречайте Contributor и Analyzer от MadCap!

09.06.2014

00Представляем вашему вниманию очередные два инструмента от компании MadCap, с помощью которых автоматизируются, упрощаются и качественно улучшаются такие процессы, как совместная работа над документом авторов, редакторов, рецензентов и руководителей – это обеспечивает MadCap Contributor, и аналитика документации – за этот процесс отвечает MadCap Analyzer.


 

MadCap Contributor

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

Добавление и просмотр контента каждым сотрудником вашей организации Читать дальше…



Не позволяйте английскому в качестве второго языка стать источником раздражения!

04.06.2014

04.06.14Сейчас большая часть вакансий сопровождается крупной надписью – «Знание английского языка обязательно». Технические писатели не стали исключением. Нередко возникает необходимость создать англоязычный документ либо перевести уже существующий. Зачастую писатель берётся за такую работу, не сомневаясь в своей компетенции – ведь, казалось бы, чего сложного, тему я знаю, термины есть в словаре, да и язык я учил с 6 лет, а однажды даже общался с живым американцем. Мы ни в коем случае не сомневаемся в вашем профессионализме, но хотим предостеречь от частой ошибки – полагаться только на свои знания и не пользоваться услугами редактора.


Те, для кого английский – второй язык, зачастую несправедливо страдают. Это потому что всё, начиная от языкового выражения, заканчивая понятиями, теряет ясность. И это может привести к неправильному впечатлению и неоправданному превосходству над ними носителей языка. Читать дальше…



Записи докладов конференции ТехДок 2013

28.11.2013

Logo_TechDoc201327 и 28 ноября прошла конференция ТехДок 2013. Ура! 🙂

Спасибо всем докладчикам, участникам, а также информационным партнёрам, которые помогли нам собрать аудиторию. Максимальное одновременное количество участников онлайн было 118 человек, и цифра не опускалась весь день ниже 100. Мы очень рады, что мероприятие вызвало интерес и собрало множество положительных откликов! Теперь конференция для технических писателей станет ежегодным событием, и мы будем рады, если аудитория будет расширяться, и в России и странах ближнего зарубежья появится сообщество технических писателей, редакторов и переводчиков. Вместе веселее! 🙂

С удовольствием принимаем отзывы на электронную почту (info@protext.su), в соцетях и на сайте. Уже есть дельные замечания и мы постараемся учесть их в будущем.

Представляем записи докладов конференции. Читать дальше…



Редактирование собственного документа

04.10.2013

01Данная заметка посвящена тому, каким образом можно редактировать документы, которые вы сами и писали.


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

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

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

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



Как работать техническим писателем, даже если у вас нет опыта (часть 3)

18.09.2013

Businesswomen shaking hands in the office.The documents are mine.Завершаем публикацию статьи о том, каким образом начинающие технические писатели могут улучшить свои навыки и увеличить шансы найти работу. В заключительной части речь пойдёт о прохождении тестирования и собеседования, а также важности прохождения стажировки.


Станьте асом в тесте на редактирование

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

Если параграф написан плохо, не говорите об этом. Откорректируйте его настолько хорошо, насколько можете, и приготовьтесь ответить, почему вы сделали эти изменения. В этой ситуации вам поможет знание правил грамматики, потому что вы можете использовать их для минимизации негатива от ваших правок. Так что вместо того, чтобы сказать «Это написано не очень хорошо», вы можете сказать нечто вроде этого: «Это предложение содержит уточнение, стоящее не на своём месте. Я исправил это перестановкой частей предложения». Если, однако, абзац написан хорошо, скажите об этом, но укажите, почему вы думаете, что он написан хорошо. Вы можете сказать примерно так: «В этом типе предложения я часто встречаю такую-то ошибку. Автор явно позаботился о том, чтобы её избежать, сделав “x” вместо “y”».

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



Работа с техническим редактором: Получил обратно исправленный текст. И что теперь?

21.06.2013

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


Десять советов как организовать и пережить встречу с техническим редактором

Примечание автора: Эта статья появилась после прочтения и ответа на статью Чери Ласота об авторстве и редактировании художественной и научно-фантастической литературы. Работа с техническим редактором имеет некоторые сходства с другими видами письма, но также и некоторые отличия.

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

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