БЛОГ
Техническое писательство в эпоху свободного программного обеспечения (часть 4)
08.11.2013
В заключительной части статьи Марк Райз рассказывает о том, почему грамотность – не самая важная черта хорошего текста, и какой залог – активный или пассивный – правильно использовать в статьях, которые увидят весь мир, и почему. Речь идёт, правда, о статьях на английском языке, но нам, русскоязычной аудитории, также важно знать об этом, потому что тема глобализации актуальна и для российского бизнеса.
4. Новая эпоха технического писательства
В эту новую эпоху, когда написанное автором доступно всегда и везде по всему миру, очень важны глобальный контекст и разные аспекты. Модель открытых источников информации и общество могут дать ещё больше информации, принимая во внимание разнообразие взглядов. Люди в мире с доступными источниками информации эффективно взаимодействуют и находятся во взаимосвязи друг с другом, несмотря на национальные и культурные барьеры на протяжении многих лет.
Из этого опыта мы можем почерпнуть основы успешной работы компании на глобальном рынке. Итак, я предлагаю вашему вниманию несколько важных советов, чтобы вы могли быть уверены в том, что всё, что пишется в вашей компании, остаётся верно функционирующим и эффективным в эту новую эпоху.
Техническое писательство в эпоху свободного программного обеспечения (часть 3)
06.11.2013
В очередной части статьи о преимуществах для технического писательства от свободного программного обеспечения речь идёт о сведениях, которые можно получить из отчётов веб-серверов Apache.
3. Количественный анализ
Даже если редактор достаточно хорош, что может работать над статьёй в одиночку, писателю требуются какие-либо количественные данные, чтобы сделать выводы. Любое дело или организация, у которой нет какого-либо количественного анализа своего контента, теряет большой кусок пирога.
Такой количественный анализ намного легче, чем вы можете подумать – спасибо использованию сегодняшних богатых данными отчётов о доступе к сайтам. Спасибо вам, ребята с проекта Apache!
Онлайн-конференция ТехДок-2013
Дорогие друзья!
27 ноября состоится первая в России конференция, полностью посвящённая вопросам организации процесса документирования программных продуктов и сервисов. Начало в 10:00.
Посещение мероприятия будет интересно:
— руководителям отделов документирования предприятий;
— профессиональным техническим писателям;
— начинающим техническим писателям;
— техническим специалистам, работа которых связана в т.ч. с компетенцией технического писателя;
— студентам вузов.
Полную информацию о конференции и программу мероприятия можно увидеть на сайте: http://protext.su/pro/?page_id=1127. Для посещения обязательна регистрация! Форму регистрации Вы найдёте на той же странице сайта.
Зарегистрировавшимся участникам будет отправлена дополнительная информация.
Ждём всех желающих!
Репост приветствуется 🙂
Техническое писательство в эпоху свободного программного обеспечения (часть 2)
01.11.2013
Вторая часть статьи посвящена тому, что публикуемые сегодня технические статьи должны обновляться, следуя за развитием тех сущностей, которые в них описаны, и полученной обратной связи.
2. Живой документ
Инструменты, инфраструктура и средства коммуникации, доступные в сообществе свободного программного обеспечения, предназначены, чтобы помочь ускорению разработки проектов. В свою очередь, они также создают невероятно эффективные ресурсы для технических писателей.
Как писатель я не только получаю огромное количество от читательских комментариев, циклически проходящих через различные источники обратной связи, но и комментарии напрямую. Мы публикуем статью, она попадает в сеть и распространяется по веб-сайтам, и в течение нескольких часов комментарии появляются по всему миру.
Если автор понимает это и вырабатывает привычку просматривать основные сайты, републикующие новости, то он получает множество преимуществ. Как я уже говорил, автор может сразу же вносить изменения в статью, реагируя на замечания и мысли читателей.
Я усвоил, что кое-что может быть пропущено в детально проработанных справочниках и руководствах пользователя, даже если автор потратил время на повторный просмотр документа, отдал его на проверку редактору и затем ещё раз окончательно прошёлся по нему перед публикацией.
Техническое писательство в эпоху свободного программного обеспечения (часть 1)
30.10.2013
В настоящей статье главный редактор портала ReallyLinux.com размышляет о том, как наличие открытого программного обеспечения влияет на процесс технического писательства
Существует четыре основных способа использовать методы и технологии открытого программного обеспечения, чтобы существенно увеличить эффективность технического писательства любой организации. Эти методы, применяемые в руководствах пользователей, маркетинговых материалах и документации к программному обеспечению, могут значительно усилить возможности технического писательства.
1. Система обратной связи с пользователем
Один из наиболее существенных аспектов совместной работы и коммуникаций – в высшей степени богатая и полезная обратная связь, существующая в сообществе свободного программного обеспечения.
Когда ваша организация публикует статью, маркетинговый документ или руководство пользователя, существует множество способов получить практически незамедлительно обратную связь.
Когда мы публикуем статью на reallylinux, автор может сразу же получить мысли от читателей, не только через прямые комментарии, а также не напрямую, через тысячи комментариев и мыслей на связанных веб-сайтах, повторно публикующих или ссылающихся на статью.
Почему разработчики пишут ужасную документацию
28.10.2013
Сегодняшняя заметка Джеки Сэмюэлс (Jacquie Samuels), консультанта в области технических коммуникаций, DITA, CMS, посвящена причинам, по которым разработчики не должны писать документацию к собственным продуктам.
Мир разработки программного обеспечения может быть стремительно развивающимся и иногда приходится очень сильно напрягаться, чтобы успеть подготовить всё к релизу. Если у компании нет отработанного процесса или отдела технической документации, часто писать документацию на продукт просят разработчиков. Действительно, кто знает продукты так же хорошо, как они?
Даже авторитетная компания может сесть в лужу с документацией, написанной разработчиком. Например, одна компания, разрабатывающая программное обеспечение, обычно пропускающая контент через отдел документирования, напортачила на небольшом, быстром проекте, который был насколько спонтанным, что никто даже и не подумал сказать: «Хорошо бы сказать группе документирования, что ведётся работа над новым продуктом, потому что, знаешь, клиентам как бы нужна документация к продукту». За день до релиза они, наконец, сказали об этом и отправили какой-то разработанный самостоятельно ими контент на быструю вычитку техническим писателем (да, этим писателем была я) в плане правки оформления, орфографии и грамматики – больше времени ни на что не осталось. И в таком виде это отправилось клиенту.
У писателя Джорджа Сондерса выдался замечательный год
25.10.2013
У Джорджа Сондерса (George Saunders) пошла полоса удач.
Писатель и профессор английского языка в Сиракьюсском университете (Syracuse University) на прошлой неделе был признан финалистом Национальной книжной премии за его сборник коротких рассказов «Десятое декабря».
В январе в «Нью-Йорк таймс мэгэзин» (прим. пер.: New York Times Magazine — Воскресное приложение к газете «Нью-Йорк таймс») заголовок гласил: «Джорж Сондерс написал лучшую книгу из тех, что вы прочтёте в этом году».
В апреле он появился в журнале «Тайм» в списке «100 самых влиятельных людей». Автор и коллега по Сиракьюсскому университету Мэри Карр (Mary Karr), пишущая для журнала, назвала Сондерса «лучшим писателем на английском – не «одним из», не «возможно», а Лучшим».
Ранее, в этом месяце, Сондерс получил награду PEN/Malamud 2013 (прим. пер.: PEN – сокращение от International Association of Poets, Playwrights, Editors, Essayists, and Novelists – Международная ассоциация поэтов, драматургов, редакторов, очеркистов и писателей-прозаиков; Malamud Bernard (1914-1986) Маламуд Бернард, Писатель) за «собрание сочинений, которое демонстрирует непревзойдённое мастерство в искусстве написания коротких литературных произведений».
Как нанимать технического писателя (часть 5)
23.10.2013
Мы завершаем публикацию статьи с советами о найме технических писателей от канадского эксперта. В заключительной части речь идёт о проверке электронной версии тестового документа и найме неопытных писателей.
Проверьте электронную версию тестового документа
Откройте тестовый документ на своём компьютере. Убедитесь, что отображение всех элементов форматирования включено, как это было, когда вы смотрели на резюме кандидата:
- Нажмите кнопку «Показать/Скрыть».
- Из меню «Таблица» выберите «Показать сетку».
- В меню «Инструменты» выберите «Настройки», а затем выберите вкладку «Вид».
- Под «Знаки форматирования» выберите флажок «Все» и нажмите «ОК».
Как нанимать технического писателя (часть 4)
21.10.2013
В очередной части статьи о том, как нанимать на работу технического писателя, речь идёт о более внимательном рассмотрении тестового документа.
Рассмотрите тестовый документ более внимательно
Теперь вернитесь к оглавлению и для примерно 20% пунктов проверьте, что заголовки записаны точно так же, как заголовки, на которые ссылаются, а также то, что они находятся на указанной странице. Другими словами, если в оглавлении написано, что вы найдёте заголовок «Бизнес-окружение» на пятой странице, откройте страницу 5 и проверьте. Так как все настольные издательские системы генерируют оглавления автоматически, любые отличия между заголовком в оглавлении и страницей, на которую он ссылается, говорит об оглавлении, которое модифицировалось вручную. Это серьёзный недостаток, показывающий, что будут обнаружены и другие серьёзные проблемы с документом. Если вы не сможете учить кандидата использованию текстовых редакторов, не нанимайте этого человека.
Как нанимать технического писателя (часть 3)
18.10.2013
Продолжаем публикацию статьи о том, как нанимать технических писателей. В сегодняшней части речь пойдёт об оценке структуры примеров работ, предоставляемых кандидатами.
Дайте общую оценку примеру документа
Просите кандидатов приносить с собой на собеседование бумажный и электронный варианты примеров их работы. Не отказывайтесь от любых примеров, даже если они «недостаточно технические». Навыки, применяемые для создания документа, который называется, скажем, «Создание превосходного теста» те же, что и применяются для создания документа с заголовком «Настройка сети».
Если бумажный вариант примера документа скреплён степлером в левом верхнем углу, уберите скрепку: вам необходимо иметь возможность переворачивать страницы таким же образом, как если бы вы смотрели в книгу. Проверьте титульный лист. Он не должен быть загромождён большим количеством элементов, а заголовок не должен быть изящным, причудливым или умным. Скорее, он должен указывать на то, что вы найдёте в книге.
Замечание: Прежде чем опробовать следующие инструкции в живом интервью, возможно, имеет смысл сперва попрактиковаться с ними с обычной книгой. Но имейте в виду, что в построении книги и построении технического документа будут некоторые различия.