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

Дистанционный курс
Навыки составления
технической документации
Цели и задачи курса




Данный лекционный курс носит характер рекомендательного пособия и адресовано, в
первую очередь, разработчикам технических документов в области финансов. Однако
данное руководство может оказаться полезным всем, кому так или иначе приходится
заниматься разработкой технических документов.
Умение понятно, аргументировано, убедительно принимать решение является, с одной
стороны, показателем профессионализма специалиста в предметной области, с другой
стороны, качественной характеристикой разрабатываемого документа.
Иными словами, для того, чтобы документ был удобочитаемым, необходимо, чтобы
представленная в нем информация была доступна для понимания, написана ясным и
простым языком; сведения, расположенные в документе, должны быть подкреплены
аргументированными
выводами
для
подтверждения
их
обоснованности;
представленная информация должна отображать надежные и достоверные данные.
Цель разрабатываемого документа – научить пользователя оперативно
формировать аргументированное суждение.
Программа курса












Микроорганизация документа
Цели
Лексические средства языка
Предметная лексика
Лексика действий и отношений
Глагольные формы
Причастия, деепричастия и прилагательные
Существительные
Числительные
Порядок слов
Удаление лишних слов
Пунктуация

















Макроорганизация документа
Цели
Структурирование информации
Обдумывание структуры документа
Составление и редактирование плана
документа
Составление плана документа в виде
графической схемы
Составление линейной (многоуровневой)
структуры документа
Размещение информации в документе
Общие принципы распределения информации
в документе
Правила составления заголовков
Построение абзацев
Особенности стиля создаваемого документа
Стилистическая культура речи
Синтаксис технической документации
Формализация изложения
Распределение информации по всей длине
предложения
Неоптимальные конструкции фраз
Макроорганизация документа


В главе Макроорганизация документа рассматриваются вопросы, связанные со структурированием
информации и составлением плана документа; рассматриваются принципы распределения
информации в документе, и разновидности стилей изложения. В главе приводятся разнообразные
примеры неоптимальных конструкций фраз и рекомендации, как их избежать.
Приведенные здесь рекомендации имеют важный методический смысл: они позволяют от чистого
листа бумаги перейти к разметке рабочего процесса, к выстраиванию логической структуры
изложения, на которую опирается вся дальнейшая деятельность разработчика.














Материал данной главы позволит приобрести навыки, которые помогут вам:
Генерировать идеи и выделять цель разрабатываемого документа.
Выделять основные направления.
Детализировать материал.
Осмысливать порядок изложения.
Составлять и редактировать план документа.
Структурировать и размещать информацию в соответствии с планом документа.
Создавать заголовки к главам и разделам документа.
Правильно строить абзацы.
Устанавливать связи между предложениями абзаца.
Распределять информацию по всей длине предложения.
Различать формы и стили языка.
Распознавать особенности стиля технической документации.
Структурирование информации













Цель раздела: помочь вам формировать с «нуля» разрабатываемый документ, который
поможет пользователю быстро получать необходимую информацию.
Задачи раздела: научить вас, как сделать документ логически последовательным и
правильно структурированным.
Логика описания документа основывается на двух базовых принципах:
От поставленной цели – к способу ее достижения.
От общего уровня описания – к более детальному описанию.
Документ не будет самодостаточным, если:
Описывать цели и не указывать способы ее достижения.
Пропускать тот или иной уровень описания.
Например, было бы не корректно, если в документе упоминать о какой-либо задаче и не
указывать способ ее решения.
С другой стороны, очень важно последовательно разграничивать все уровни описания и
не допускать их смешения.
Основные моменты при создании структуры документа:
– Обдумывание структуры изложения;
– Составление и редактирование плана документа.
Обдумывание структуры документа


Отметим сразу, что это трудоемкий процесс: он занимает у разработчика большую часть
времени разработки структуры документа.
Что же делать на начальном этапе разработки документа? Редко кому незнакома паника
перед чистым листом: с чего начать? В этой ситуации хорошо помогает методичное
обдумывание структуры изложения.
Составление и редактирование плана
документа




Существует множество методов составления плана документа. Однако мы хотим
остановиться на наиболее популярных и результативных приемах структурирования
документа:
Схематичное представление.
Линейное представление.
Напомним, что структурирование выполняется двояким образом: в целом и в
отдельных частях документа. В этом разделе мы остановимся на процессе составления
плана документа, который является важным этапом в структурировании документа в
целом.
Размещение информации в документе.
Общие принципы распределения
информации в документе





Одним из главных правил размещения теста в документе является принцип экономии
усилий пользователя. Это означает, что читатель документа должен затрачивать
минимум усилий на поиск и получение информации. Только при соблюдении этого
принципа распределение информации в документе будет рациональным.
Теперь сформулируем ряд рекомендаций, следуя которым, можно осуществить этот
принцип на практике. На наш взгляд наиболее подходящими для решения этого вопроса
являются две модели, описание которых мы представим ниже. А именно распределение
информации в документе определяется:
– последовательностью изложения материала;
– соображениями удобства для пользователя документа.
Насколько они приемлемы для вас, покажет процесс разработки документа. Отметим,
что автор в праве выбирать наиболее подходящую модель для разработки.
Правила составления заголовков









Составление заголовков, строго говоря, относится уже к этапу словесного воплощения
замысла темы. Тем не менее, мы представляем эту тему в данной главе, поскольку
заголовки разделов:
– играют значительную роль в структурировании информации;
– делают более очевидной общую структуру документации;
– облегчают чтение документа и поиск в нем необходимых сведений.
Подчеркнем, что высокая культура заголовка не только придает документу
завершенность, но и дисциплинирует творческое мышление разработчика.
Примеры и содержание раздела помогут вам понять, каким критериям качества
должен отвечать заголовок:
– Заголовок не должен быть слишком длинным.
– Заголовок должен иметь прозрачную и по возможности простую синтаксическую
структуру.
– Заголовок должен сообщать необходимый минимум информации о содержании
раздела.
Построение абзацев



Вопросы организации текста в отдельных частях документа являются
основным средством структурирования документа.
Цель данного раздела: научить вас распознавать логическую структуру
абзаца.
Представленные рекомендации научат вас, как размещать информацию в
абзацах, в соответствии с правилами построения предложений. Следуя этим
рекомендациям, вы можете быть уверены в том, что документ составлен
правильно.
Особенности стиля создаваемого
документа. Стилистическая культура
речи






В главе Особенности стиля создаваемого документа рассмотрены основные проблемы,
связанные со стилем и синтаксисом создаваемого документа.
В данной главе не представлен курс синтаксиса русского языка, да в этом и нет
необходимости. Но, как и в случае с лексикой, необходимо понимать, какими
возможностями располагает автор документа в области построения словосочетаний, и
фраз и какие ограничения накладываются на его деятельность в этой области.
Основные отличия хорошего стиля от плохого стиля состоят в следующем:
Хороший стиль облегчает восприятие документа. Следует помнить, что,
ваш адресат перед тем, как взяться за написанную вами документацию, наверняка
читал другие книги и имеет некоторые представления о том, каким бывает стиль того
или иного текста. Если ваш текст обманывает ожидания, это затрудняет его восприятие.
Повышает авторитет документа в глазах читателя. Во-первых, грамотная
речь вызывает уважение к ее автору. Во-вторых, современный читатель сразу
определит, что с ними разговаривает компетентный и грамотный специалист, а не
случайный человек.
Дисциплинирует мышление разработчика документа. Стилистически
безграмотный текст чаще всего бывает двусмыслен и противоречив. Очень часто
плохой стиль свидетельствует о недостаточной продуманности излагаемых мыслей.
Синтаксис технической документации






В данном разделе мы не будем останавливаться на изложении курса синтаксиса
русского языка. Мы сосредоточимся лишь на вопросах, которые требуют особого
обсуждения:
– Формализация изложения.
– Порядок слов в предложении.
– Распределение информации по всей длине предложения.
– Ритмическая организация речи.
Мы напомним вам, что такое синтаксис языка, разберемся в том, какими
возможностями располагает разработчик документа в области построения
словосочетаний и фраз.
Неоптимальные конструкции фраз


В данном разделе мы поговорим о наиболее часто встречающиеся недостатках в
документах и дадим рекомендации, как их избежать. Эти недостатки зачастую приводят
к неоптимальным конструкциям фраз, что делает содержание документа не понятным
для пользователя. Для того чтобы восприятие текста было легким для пользователя,
необходимо бороться с такими конструкциями.
Умение писать сразу ясно и четко приходит не сразу. Необходимо владеть
определенными навыками для упрощения и оптимизации текста. Мы сформулируем
некоторые рекомендации, которые помогут вам сделать свой документ удобочитаемым
для пользователя.
Микроорганизация документа






В главе Микроорганизация документа мы познакомим вас с особенностями
использования лексических ресурсов языка, расскажем о порядке слов в предложении, а
также о некоторых правилах пунктуации, вызывающих наибольшие трудности. По
каждой теме мы представим рекомендации в рамках микроорганизации документа,
которые помогут вам при изложении материала.
Представленная в данной главе информация позволяет приобрести навыки, которые
помогут вам:
Использовать необходимые для работы лексические ресурсы языка.
Пользоваться предметной лексикой и лексикой действий и отношений.
Разбираться в правильном построении предложений.
Аккуратно использовать пунктуацию.
Лексические средства языка






В этом разделе мы обратим ваше внимание к языковым средствам выражения мысли,
напомним вам, что такое лексика языка, расскажем об основных группах лексики,
выделим основные лексические средства для выражения действий и отношений, дадим
общие рекомендации по применению лексических средств языка в разработке
технических документов.
Мы будем рассматривать язык и его элементы с точки зрения стоящих перед нами
практических задач. Поэтому лексические ресурсы языка рассматриваются и
классифицируются нами исходя из того, что они позволяют описывать и какого рода
задачи они позволяют решать.
Рассморим на примерах две большие группы лексики:
– Предметно-понятийная лексика.
– Лексика действий и отношений.
Эти две группы, конечно, не исчерпывают всей лексики, которая используется в
документации, однако именно они привлекают наше внимание в первую очередь. Ваша
задача состоит в том, чтобы, при выражении той или иной мысли, отдавать себе отчет в
том, какими средствами вы располагаете, чтобы ее выразить.
Лексика действий и отношений









Цель раздела: научить вас некоторым приемам использования предметно-понятийной
лексики.
Предметно-понятийную лексику можно сравнить со скелетом, который образует
прочную основу документации. Однако он неподвижен без развитой системы мышц.
Такую мышечную систему образует лексика действий и отношений, которая отличается
своим разнообразием от предметно-понятийной лексики.
Например, одно и то же действие или отношение может быть выражено несколькими
способами (глаголом, причастием, существительным и пр.). Можно сказать, что именно
разнообразная лексика действий и отношений обеспечивает гибкость языка
документации и широкий набор ее возможностей.
В данном разделе напомним и рассмотрим на примерах основные лексические средства
для выражения действий и отношений:
Глагольные формы.
Причастия, деепричастия и прилагательные.
Существительные.
Числительные.
Также расскажем вам, как выразить действие или отношение различными
лексическими средствами, в каких случаях какие средства предпочесть и как перейти от
одного способа описания к другому.
Порядок слов. Удаление лишних слов







Качество технического документа во многом зависит от того, как правильно построены фразы и
абзацы в вашем документе. Поэтому в этом разделе мы поговорим о порядке слов в предложении.
Вызвано это, прежде всего тем, что в русском языке порядок слов может существенно варьироваться, а
это приводит к изменению смысловой нагрузки в предложении. Это означает, что порядок слов в
предложении является дополнительным средством передачи информации.
Каким образом это происходит?
– За счет изменения порядка членов предложения.
– За счет распределения информации по всей длине предложения.
В этом разделе мы на примерах продемонстрируем вам, как меняется смысловая нагрузка в
предложении при изменении в нем порядка слов.
Напомним вам, что назначение технических документов состоит в том, чтобы быстро и точно передать
информацию. Хороший технический писатель может выразить свою мысль лаконично: вместо
нескольких неопределенных слов он использует одно точное слово, тем самым экономит время
занятого человека, который изучает его документ.
Научим вас , как следить за количеством соединяющих слов в предложении.. В каждом предложении
есть работающие слова и соединяющие слова. Работающие слова несут смысловую нагрузку
предложения. Соединяющие слова выполняют важную функцию: они связывают работающие слова в
предложении. Однако избыток соединяющих слов делает предложение сложным для восприятия и
показывает, что оно плохо согласовано.
Пунктуация




В этом разделе мы напомним вам о правилах расстановки знаков препинания. Причем,
представленные в разделе правила пунктуации, не будут охватывать все возможные
грамматические ситуации: здесь будут включены случаи, вызывающие наибольшие
трудности. Однако и они дадут вам определенные навыки для правильного
использования знаков препинания, чтобы наилучшим образом передать смысловое
значение документа.
Для начала расскажем вам о назначении, и напомним о знаках препинания русской
пунктуации.
Назначение пунктуации заключается в том, чтобы обеспечить читателю правильное
понимание смысла написанного. Текст, написанный без знаков препинания, читается
значительно медленнее, чем оформленный текст. Поскольку правильное понимание
текста зависит от смыслового членения предложения, постольку основой пунктуации
является смысловое деление речи.
Отметим, что пунктуация настолько важна, что она может изменить смысловое
значение предложения. В некоторых случаях от расстановки знаков препинания смысл
предложения может меняться на противоположный. Поэтому к этому предмету
необходимо относится с должным вниманием.