Категория: Руководства
Каким бы гениальным ни был изобретатель, программист или рационализатор, порой его творениями просто невозможно пользоваться по назначению. Виной тому – неверно составленная инструкция по эксплуатации или ее полное отсутствие. Но даже гениальные изобретатели иногда пишут такие инструкции, что кроме узких специалистов никто эти бумаги прочесть не может. Так как же правильно составить такой необходимый документ?
Вам понадобится
Многие руководства пользователя написаны так, что с программой проще разобраться самому, чем читать справку. И до недавней поры не было инструмента, который бы помог решить эту проблему, объединив все полезные знания о текстах в один документ.
Взялись за правилаНе так давно компанией «Философт» совместно с Институтом русского языка был разработан проект стандарта РФ Стиль изложения документации пользователя программного средства. Общие требования. Этот стандарт пока не утвержден и, следовательно, не введен в действие.
Сам факт появления этого документа — радостная новость, и не только для технических писателей, но и для пользователей, ведь теперь они могут надеяться на появление понятных и четких документаций к программам.
Но все оказалось вовсе не так радостно, как хотелось бы. Основное разочарование (даже, скорее, огорчение) вызвали у меня при прочтении правила, описанные в пунктах 6.6.2.3. — 6.6.5.3. Чтобы проблема была ясна и понятна, приведу некоторые выдержки из стандарта:
6.6.2.3. В документации пользователя не допускаются шутливые и иронические высказывания. 6.6.3. С лексической точки зрения нейтрально-книжный стиль изложения предполагает использование эмоционально-нейтральной литературной лексики, причем отдается предпочтение словам с узкими и точными значениями. 6.6.3.1. Из текста исключаются элементы профессионального жаргона, а так же следующие категории слов и выражений: — разговорные или близкие к разговорным слова и выражения (например, «плохой», «прекрасный», «глупый» и т.д.). 6.6.3.2. В изложении отдается предпочтение словам и выражениям с более узким и, как следствие, более точным значением перед словами и выражениями близкими по смыслу, но с более широким и общим значением. Например, вместо «большой» в зависимости от контекста употребляется «значительный», «существенный», «вместительный» и т.д. вместо «высокий» — «имеющий значительный размер по вертикали», «расположенный на значительной высоте», «обладающий более высоким тоном» и т.д. В документации пользователя употребляются, главным образом, тяготеющие к книжному языку специализированные слова и выражения. Во избежание неточных формулировок рекомендуется избегать общеупотребительной лексики, заимствованной из обыденной (непрофессиональной) речи. 6.6.4.3. … не допускаются экспрессивные и близкие к экспрессивным средства словообразования… Уменьшительные, увеличительные, ласкательные, пренебрежительные и т.п. суффиксы исключаются из употребления как средства образования имен существительных и прилагательных с дополнительными оттенками значения…
Стандарт подразумевает универсальное применение этих правил, что, на мой взгляд, ошибочно. Нам предстоит понять, когда эти правила верны, и в каких случаях они могут быть опровергнуты.
Это справочная?Для четкости и понимания проблемы разделим документацию пользователя на два типа:
Стили изложения этих текстов должны различаться, т.к. справка и учебник решают различные задачи пользователя. Представим ситуацию, в которой мы обращаемся к справке. Например, мы — пользователи — работаем в текстовом редакторе, и у нас возникает срочная необходимость вставить сноску. Мы раньше никогда этого не делали, и, покопавшись в меню, так и не нашли подходящей функции. В этом случае нам и поможет справка. Формулируем запрос для поиска, и без проблем находим пошаговую инструкцию для вставки сносок: укажите — выберите — щелкните — нажмите. В такой инструкции пользователю не нужна лишняя информация. Ему совсем не нужно знать, в каких случаях может возникнуть та или иная проблема, ведь если он обратился к справке, то проблема уже возникла. Основная задача справки — быстро помочь пользователю разобраться. Быстро узнать, быстро понять, быстро найти. Именно поэтому текст справки должен быть четким, ясным и прозрачным, содержать только «голые» факты, которые пользователь будет выдергивать по мере необходимости. Другими словами, стиль изложения справки должен отвечать всем правилам стандарта от Философт.
Чего нельзя сказать о втором типе документации, учебнике. Определим, в каких случаях мы (снова простые пользователи) обращаемся к подобной книге (или документу). Мы совсем не знакомы с программным средством, или знакомы с ним очень поверхностно, или знакомы с предыдущей версией программы. Нужно узнать, что нам предстоит: зачем вообще существует это программное средство, с какими проблемами мы можем столкнуться, какие функции могут быть полезны, а какие — вовсе не нужны и т.д. Учебник предназначен для последовательного чтения. Предполагается, что пользователь не выдергивает нужную информацию, а читает по главам, как книгу (именно поэтому учебники, как правило, издаются в книжной форме). Представьте, что вам предложили прочитать книгу, где не допускаются шутливые и иронические высказывания, написанную нейтрально-книжным стилем изложения, который предполагает использование эмоционально-нейтральной литературной лексики. Определенно, вы получите всю нужную информацию, но захотите ли вы прочитать такую книгу до конца? Где гарантия, что нейтрально-книжный текст не завязнет в зубах, так и не сумев донести всю полезную информацию?
Позовите автора.Руководство пользователя — это полноценный текст, достойный быть интересным и захватывающим. Поэтому у автора учебника должна стоять задача не только донести полезные факты о программном средстве, но и сделать это красиво. Например, переводчик и литератор Нора Галь в своей книге о языке «Слово живое и мертвое» приводит огромное количество примеров неживой, неестественной речи. Она, конечно, не писала о стиле документаций, но это вовсе не отменяет всех претензий к сухости, жесткости, неуклюжести языка. Книги Норы Галь (как ее переводы художественной литературы, так и книги о языке), а также, к примеру, книги Чуковского («Живой как жизнь») я рекомендовала бы к прочтению всем техническим писателям, собирающимся слепо (и некритически) следовать стандарту Философта.
Также каждому техническому писателю будет полезно прочитать статью «How to Publish a Great User Manual» (Как написать хорошее руководство пользователя ) дизайнера интерфейсов Брюса Тоньяцини (Bruce Tognazzini), одного из авторов дизайна Макинтош. Вот сравнительный пример текстов из этой статьи. Достаточно было заменить абзац на одно точное, но понятное предложение, чтобы чтение учебника стало интересным (ниже — мой перевод цитаты):
One key concept, centered on what Macintosh extensions are and why they cause trouble, underlies all of Conflict Catcher. Let’s see how two different writers present it: From the Conflict Catcher 4 manual: Since you first began using your Macintosh, you’ve probably extended the services that it provides on more than one occasion to keep pace with your changing needs….All these seemingly unrelated changes have one important thing in common-the addition of specialized files to your system to make new services available….This growth has created…the need to be able to troubleshoot problems they can cause by interacting with one another or other parts of the system. This is clear and competent, but consider David Pogue’s introduction, in the Conflict Catcher 8 manual, of the same concept: Your Mac’s software is the result of an accidental collaboration among hundreds of programmers. Now, that’s great writing. Из-за того, что существуют расширения для Макинтош, и они могут вызывать проблемы, и появился Conflict Catcher. Вот как это описали два разных технических писателя. Из руководства пользователя Conflict Catcher 4: С тех пор, как вы начали пользоваться Макинтошем, вы, вероятно, не раз расширяли его функции для того, чтобы они соответствовали вашим запросам… Все эти не связанные на первый взгляд изменения похожи в одном — они требуют записи в систему специальных файлов для того, чтобы новые сервисы были доступны… Увеличение количества расширений повлекло за собой необходимость в выявлении и решении проблем, неизбежно возникающих при взаимодействии разных частей системы друг с другом. Это вполне понятный и соответствующий действительности текст, но посмотрите, как эта же идея описана в другом руководстве (уже к Conflict Catcher 8): Программное обеспечение вашего Макинтоша — это результат совместной работы сотни программистов, не подозревающих друг о друге. Вот это — настоящий текст.
Другой пример: издательство Microsoft Press издает руководства пользователя, абсолютно отличные по стилю от простых справок продуктов Microsoft. Вот предложение, с которого начинается глава «Подключение к другому компьютеру с использованием удаленного помощника» в руководстве по работе с Windows Vista (Windows Vista Inside Out ).
If you’ve ever tried to help a novice user troubleshoot a Windows problem over the phone, you know how frustrating the entire process can be. Если вы когда-нибудь помогали новичку решать проблемы с Windows по телефону, вы наверняка знаете, каким утомительным может быть этот процесс.
Одно простое предложение, в котором содержится и ироническая интонация, и жизненный опыт, и просто отсылка к возможным проблемам. Но это делает текст читабельным и живым, хоть и нарушены пункты стандарта о нейтрально-книжном стиле, и заимствованиях слов из обыденной речи (в данном случае слово frustrating).
А вот предложение из вводной главы руководства к программе Flying Logic (Thinking with Flying Logic, Robert McNally ):
Even if you don’t use Flying Logic, I hope you will find it a concise and useful introduction to some powerful ways you can improve your business and personal life. Даже если вы не будете пользоваться Flying Logic, я надеюсь, эта книга укажет возможные пути для улучшения вашего бизнеса и жизни в целом.
Ключевые слова: «улучшить вашу жизнь». И снова нарушены правила стандарта: и от темы отступили, и предпочтения словам с узкими и точными значениями не отдали. Из всего сказанного можно вывести правило для стиля изложения книг-руководств пользователя: текст должен быть живым, интересным, авторским. Если автору присущ ироничный стиль, или автор, к примеру, любит давать советы, опираясь на собственный жизненный опыт, и при этом его тексты интересно читать — ничего не должно мешать ему сохранить свой стиль и в тексте мануала.
Сейчас, пока стандарт еще находится только в стадии проекта, самое время обсуждать и находить компромиссы. Если стандарт будет утвержден с такими правилами, пользователи будут вынуждены читать сухие и вязкие мануалы, а технические писатели будут обречены их писать. Однако, достаточно лишь заменить в правилах слова «не допускается» и «исключается» на «не рекомендуется», и ситуация уже изменится в лучшую сторону. Ведь технические писатели, как поэты и творческие личности, не должны терпеть запретов на использование живого слова в своих текстах.
Создание документации к программному обеспечению – одно из самых востребованных направлений деятельности технического писателя. А значит, чтобы стать незаменимым (а в нашей сфере деятельности незаменимые бывают) специалистом, нужно освоить и это направление.
Вы руководитель проекта по разработке софта и хотите получить всю документацию к нему без лишних забот? Наши специалисты с удовольствием сделают для Вас эту работу! Подробнее на этой странице: Разработка технической документации на аутсорсинге .
Или Вы технический писатель и желаете повысить свою квалификацию? Тогда — добро пожаловать на наш курс «Разработка технических текстов и документации» .
Хорошая документация к программному обеспечению, будь то спецификация для программистов и тестеров, технический документ для внутренних пользователей или программное руководство и файлы справки для конечных пользователей, помогает человеку, работающему с программным обеспечением, понять его особенности и функции. Хорошая документация к программному обеспечению специфична, кратка, актуальна и предоставляет всю информацию, нужную человеку, использующему программное обеспечение. Ниже приведены инструкции о том, как написать документацию к программному обеспечению для технических специалистов и конечных пользователей.
Метод 1 из 2: Пишем документацию для технических специалистов
Copyright (C) 1996-2015, System SoftLab.
Дата последнего обновления
27 августа 2015 года
