Что такое техническая документация? Техдокументация - это «совсем не то, о чем вы подумали». И совсем уж не то, что предлагают нам всяческие ...педии и прочие сетевые словари. Точные, исчерпывающие и узаконенные по технической тематике обитают исключительно в. Как удобнее их искать? Редакция от 20.06.2018.

Что такое техническая документация?

Создан 01.10.2009 9:48:27

«техническая документация» послужит нам всего лишь в качестве примера, применимого к технической терминологии в целом.

Итак, указанный термин в различных сетевых источниках трактуется совсем уж безграмотно. Определение, приведенное на рисунке, вообще не выдерживает никакой критики, комментарии излишни.

В наиболее приемлемом (из всех найденных) определении техдокументации «по Педевикии», изображенном на рисунке ниже, предельно низок - в разделе Стандарты ссылки на нормативные документы имеются, но не на те, на которые должны быть. Отсутствуют ссылки на самые важные, а именно на:

  • руководящий документ;
  • на автоматизированные системы (КСАС), в состав которого входят и.

Примечание от 12.01.2015 г. - В ходе дальнейшего «потрошения» для пополнения открываются новые, в частности:

Техническая документация по Р 50-605-80-93

В документе Р 50-605-80-93 Система разработки и постановки продукции на производство. Термины и определения техдокументация представлена как «Совокупность, необходимая и достаточная для непосредственного использования на каждой. К технической документации относятся и, и т.д. Техническую документацию можно подразделить на исходную, проектную, информационную. К исходной относятся: , исходные, по разработке продукции, выполняемые в процессе, техническое задание. К проектной документации относятся: для конструкторской документации - , ; для технологической - предварительный проект. К рабочей документации - , . К информационной документации - , расчета экономической эффективности и цен () продукции, каталоги, отчет о, акты и об, о и др. [из п. 1.6.1 Р 50-605-80-93]»

Но Р 50-605-80-93 дает определение техдокументации на в целом. Для, являющихся частным случаем промышленной продукции, предусмотрены ЦЕЛЫХ ДВА определения

Техническая документация на автоматизированную систему по ГОСТ 34.003-90 и ГОСТ 34.201-89

Согласно ГОСТ 34.003-90 техническая документация на АС есть «Комплект взаимоувязанных , полностью определяющих технические к, проектные и организационные решения по созданию и АС [из п. 5.1 ГОСТ 34.003-90]»

В ГОСТ 34.201-89 имеется иная трактовка, а именно: «Документация на - комплекс взаимоувязанных , в котором полностью описаны все решения по созданию и системы, а также документов, подтверждающих системы и готовность ее к () [из п. 1 прил. 1 ГОСТ 34.201-89]».

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

Техническая документация на военную технику по Р 50-605-80-93

Особый случай. Потому и определение техдокументации на нее идет отдельной статьей - «Совокупность, создаваемых для непосредственного использования их на различных. Основными видами на военную технику являются:

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

[из п. 2.5.3 Р 50-605-80-93]»

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

Техническая документация по ГОСТ Р 54089-2010

Еще одно очень милое, краткое и емкое определение техдокументации - «Совокупность и, используемой для изготовления, и [из п. 3.1.12 ГОСТ Р 54089-2010]».

  • для поиска соответствующей случаю нормативной документации достаточно сделать запрос в любой с «гост термины и определения» - откроется список. Это быстрый, но не отличающийся особой способ. Более того, терминология частенько содержится в ГОСТах, которые могут быть и не найдены по указанным;
  • более сложным и запутанным является поиск терминологии в Общероссийском классификаторе стандартов. Но результат поиска по запросу «термины и определения» в подходящем разделе ОКСа будет и исчерпывающим по своей полноте.

Вот одна из ссылок на ОКС - standartgost.ru/0/101-obscherossiyskiy_klassifikator_standartov

Все многообразие технической документации можно разделить на три группы (см. рис.8):

1) Нормативно-техническая документация, которая устанавливает единые правила оформления, учета, хранения и использования технической документации.

2) Конструкторская документация, которая дает полное представление о составе изделия в целом и его составных частей, а также содержит документацию по эксплуатации и ремонту, необходимые данные для разработки технологической документации и

В свою очередь конструкторская документация подразделяется на:

Проектную документацию

Эксплуатационную и ремонтную документацию.

3) Технологическая (рабочая) документация, предназначенная для изготовления и испытаний опытного или серийного образца изделия.

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

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

Классификация всего многообразия конструкторской документации приведена на рис.9


Чертежи включают в себя:

1. Чертеж детали.

2. Сборочный чертеж СБ.

3. Чертеж общего вида ВО.

4. Теоретический чертеж ТЧ.

5. Габаритный чертеж ГЧ.

6. Монтажный чертеж МЧ.

Чертеж детали: изображение детали и данные, необходимые для ее изготовления.

Сборочный чертеж: изображение сборочной единицы и данные, необходимые для ее сборки, изготовления и контроля.

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

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

Габаритный чертеж: (упрощенная) изображение изделия с габаритами, установочными и присоединительными размерами.

Монтажный чертеж: (упрощенная) изображение изделия, содержащее данные для его установки (монтажа).

Схема: условные изображения или обозначения составных частей изделия и связи между ними.

Схемы по многообразию видов подразделяются см. рис.10

Схемы подразделяются на следующие типы схем (на примере электрической):

1. Структурная (вид схемы – Э, тип схемы – 1).

2. Функциональная (вид схемы – Э, тип схемы – 2).

3. Принципиальная (вид схемы – Э, тип схемы – 3).

4. Схема соединений (монтажная) (вид схемы – Э, тип схемы – 4).

5. Подключения (вид схемы – Э, тип схемы – 5).

6. Общая (вид схемы – Э, тип схемы – 6).


7. Расположения (вид схемы – Э, тип схемы – 7).


Вид схемы зависит от элементов и связей, входящих в состав изделия. Тип схемы зависит от ее назначения.

Структурная схема – определяет основные части изделия, их назначение, их взаимосвязи (для общего ознакомления).

Функциональная схема – поясняет процессы, происходящие в изделии, раскрывает функции, выполняемые отдельными частями и устройством в целом (для изучения, для разработки принципиальной схемы, для наладки, эксплуатации и ремонта изделия).

Принципиальная схема – дает детальное представление о принципах работы изделия, об элементах и связях между ними (для разработки чертежей, схем соединений, контроля и ремонта).

Схема соединений – определяет связи составных частей изделия, а также марки, сечения, длины монтажных проводов, кабелей и места их присоединения (для наладки, эксплуатации и ремонта).

Схема подключения – показывает внешние подключения изделия (при монтаже изделия на месте эксплуатации, ремонте и эксплуатации).

Схема общая – определяет соединение составных частей между собой на стадии эксплуатации.

Схема расположения – определяет относительные расположения составных частей, а при необходимости расположение проводов, жгутов, кабелей на месте эксплуатации (для эксплуатации).

Текстовая КД (текстовые документы).

Спецификация – документ, содержащий перечисление состава сборочных единиц, комплекса или комплекта.

Ведомости.

1. ВС – ведомость спецификаций – перечень всех спецификаций.

2. ВД – ведомость ссылочных документов – перечень документов, на которые имеются ссылки в КД.

3. ВП – ведомость покупных изделий – перечень покупаемых изделий, применяемых в составе с соответствующими организациями.

4. ВИ – ведомость согласования примененных изделий – подтверждение согласования с соответствующими организациями.

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


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

Стоит также отметить, что существует несколько видов такой технической документации, к числу которых можно отнести следующие:

Конструкторский вид документации - он включает в себя эксплуатационную, а также ремонтную документацию;

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

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

Что же касается осуществления проведения таких работ, как {разработка технических условий}, то они имеют свои особенности. Так, разработка технических условий самым непосредственным образом связана с оформлением документации проектного типа. Требования, которые предъявляются к техническим условиям, должны быть в соответствии с государственными нормативными используемыми стандартами.

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

Правила и требования к поставке;

Проведение конечных испытаний при определении продукции в общее использование;

Условия соблюдения и правильность использования продукции;

Правила, при которых необходимо соблюдать правильную транспортировку, использовании, хранение и другие не менее важные и полезные особенности.

К технической документации относятся также такие документы, как руководство по эксплуатации. Оно представляет собой такой информации, которая содержит такие важные данные, как особенности конструкции, а также принципы функционирования такого оборудования, его основные параметры, а также объекты, входящие в его состав.

Не менее важную особенность при оформлении руководства по эксплуатации имеют такие важные параметры, как прописывание сведений по осуществлению безопасных условий при работе с подобным оборудованием.

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

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

Техническая документация

система графических и текстовых документов, используемых при конструировании, изготовлении и эксплуатации промышленных изделий (деталей, сборочных единиц, комплексов и комплектов), а также при проектировании, возведении и эксплуатации зданий и сооружений. Т. д. на промышленные изделия определяет вид, устройство и состав изделия и регламентируется Единой системой конструкторской документации (ЕСКД) и Единой системой технологической документации (ЕСТД), входящими в Государственную систему стандартизации СССР (см. Стандарт).

ЕСКД - комплекс государственных стандартов, устанавливающих правила и положения о разработке, оформлении, комплектации и обращении конструкторской документации, в том числе: общие положения по выполнению документов, правила выполнения чертежей, текстовых документов и схем, условные графические обозначения, правила выполнения эксплуатационной и ремонтной документации, правила обращения документов (учёта, хранения, дублирования и внесения изменений). Комплектность конструкторских документов на конкретное изделие определяется его видом и стадией разработки. За основные виды: конструкторских документов принимают: для деталей - чертёж детали, для сборочных единиц, комплексов и комплектов - спецификацию (См. Спецификация). Кроме того, к конструкторским документам относят схемы (См. Схема), ведомости, Технические условия и др.

ЕСТД - комплекс государственных стандартов, устанавливающих правила и положения о порядке разработки, оформления, комплектации и обращения технологической документации. К технологическим относятся документы, которые определяют технологию изготовления изделия и содержат необходимые данные для организации производства, в том числе: маршрутные и операционные карты, карты эскизов и схем,) спецификация технологических документов, технологическая инструкция, ведомость по материалам и оснастке. Операционные карты технологических процессов выпускаются на изготовление отливок, раскрой заготовок, механическую и термическую обработку и т. п. (см. Технологическая документация).

В. В. Данилевский, В. Н. Квасницкий.


Большая советская энциклопедия. - М.: Советская энциклопедия . 1969-1978 .

Смотреть что такое "Техническая документация" в других словарях:

    техническая документация - документация технического обеспечения — [Л.Г.Суменко. Англо русский словарь по информационным технологиям. М.: ГП ЦНИИС, 2003.] Тематики информационные технологии в целом Синонимы документация технического обеспечения EN hardware… … Справочник технического переводчика

    Система документов, разрабатываемых и используемых в процессе проектирования, изготовления, эксплуатации и ремонта изделий военной техники. EdwART. Толковый Военно морской Словарь, 2010 … Морской словарь

    Техническая документация Энциклопедия права

    Техническая документация - 8. Техническая документация Конструкторская и технологическая документация Источник: ГОСТ 23200 78: Суда прогулочные гребные и моторные. Общие требования при поставке на экспорт …

    Для улучшения этой статьи желательно?: Дополнить статью (статья слишком короткая либо содержит лишь словарное определение). Найти и оформить в виде сносок ссылки на авторитетные источники, подтверждаю … Википедия

    техническая документация (ТД) - 3.17 техническая документация (ТД): Совокупность конструкторской, технологической, проектной и программной документации, используемой для изготовления, монтажа, эксплуатации, ремонта и утилизации продукции. Источник … Словарь-справочник терминов нормативно-технической документации

    Техническая документация. - 1.5.7. Техническая документация. Исполнитель должен иметь и хранить в укомплектованном виде всю техническую, эксплуатационную и исполнительную документацию. Подлинники этих документов хранятся у Пользователя (владельца) системой водоотведения. В… … Словарь-справочник терминов нормативно-технической документации

    техническая документация на ОС - 3.10 техническая документация на ОС (ТД): Технические условия, инструкция, руководство и другая документация, устанавливающая требования к ОС и их применению. Источник: ГОСТ Р 53292 2009: Огнезащитные составы и в … Словарь-справочник терминов нормативно-технической документации

    Совокупность документов, используемых для орг ции и осуществления произ ва, испытаний, эксплуатации и ремонта продукции, стр ва, эксплуатации и ремонта зданий ираэл. сооружений. Осн. виды Т. д.: проектная и рабочая (в стр ве), конструкторская и… … Большой энциклопедический политехнический словарь

    Техническая документация - см. Договор строительного подряда … Большой юридический словарь

Книги

  • , Штейнберг А.И.. Настоящая книга посвящена составлению, систематизации и ведению исполнительной технической документации в процессе организации строительства, его осуществленияи сдачи объектов в эксплуатацию.…
  • Исполнительная техническая документация в строительстве , Штейнберг А.И.. Эта книга будет изготовлена в соответствии с Вашим заказом по технологии Print-on-Demand. Настоящая книга посвящена составлению, систематизации и ведению исполнительнойтехнической…
  • Перевод

Введение

Эти правила - не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.

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

Итак - эти 7 правил:

  1. Скука убивает
  2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
  3. Пишите в соответствии с правильно сформированной структурой
  4. Избегайте неоднозначных местоимений
  5. Ясность = иллюстрации + слова
  6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример
  7. Не опасайтесь переделок

1. Скука убивает

Это правило является, по-видимому, самым трудным для формализации и самым важным по необходимости соблюдения. В современном мире интернета действует много сил, борющихся за внимание вашего читателя. Скучное стандартное описание работать не будет. При любых обстоятельствах ваш читатель желает, чтобы было увлекательно и информативно. Поэтому, если ваш текст неясный или неинтересный, то читатель просто щёлкнет пресловутую кнопку «Далее» и перейдёт на другую веб-страницу или на другую ТВ-программу или на свою страницу в Фейсбуке.

Самый простой путь, который я нашёл для пробуждения интереса у читателя, состоит в том, чтобы интересно было мне самому. Я всегда прилагаю значительные усилия, чтобы написать такую статью, которую сам хотел бы прочитать. Я стремлюсь получать удовольствие от того, что пишу. Если мне скучно, то заскучает и читатель. Если я запутался, то запутается и читатель. Если меня не волнует рассматриваемая тема, то читатель, тем более, не взволнуется. Всё очень просто!

Мне нравится юмор, поэтому я стараюсь сделать мои литературные технические «творения» забавными, но, конечно, без ущерба для ясности. Пытаюсь разговаривать с читателем, а не поучать его. Пишу о делах, которые, действительно, имеют значение для меня. Широко использую иллюстрации, чтобы предотвратить неясность для читателя.

И снова, всегда стараюсь сделать процесс чтения увлекательным. Я всегда помню, что пишу в конкурентной среде. Имеется множество контента, стремящегося привлечь внимание читателей. Таким образом, мой совет по правилу № 1: если ваши тексты будут интересны вам, то они будет интересными и для читателя.

2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд

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

Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.

3. Пишите в соответствии с правильно сформированной структурой

Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в метро Нью-Йорка (469 станций!) без схемы. Вы можете оказаться где угодно, но это «где угодно» может оказаться совсем не тем местом, куда вы предполагали попасть.

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

Имеются два правила структурирования, которые я всегда использую:

1. Раздел подуровня требует наличия, как минимум, одной позиции.
2. На каждом уровне структуры должно быть, как минимум, два предложения.

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

Листинг 1: неправильно сформированная структура

1.1. Шаги, требуемые для приготовления шипучего напитка

1.1.1. Подготовка ингредиентов

1.1.2. Смешивание ингредиентов шипучего напитка

1.1.3. Подача шипучего напитка

Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: "1.1. Шаги, требуемые для приготовления шипучего напитка ". Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.

Посмотрите листинг 2 внизу. Обратите внимание, что у уровня 1 теперь имеются три подуровня, из которых раздел «Смешивание ингредиентов шипучего напитка» содержит позиции. Одиночный уровень «Шаги, требуемые для приготовления шипучего напитка» удалён.

Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка» ?.. Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу.

Листинг 2: правильно сформированная структура, нарушающая правило двух предложений

1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка

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

1.1. Подготовка ингредиентов

1.3. Подача шипучего напитка

Обратите внимание, что, хотя листинг 2 демонстрирует структуру с правильно сформированным подуровнем, в контенте раздела уровня 1 имеется только одно предложение. Присутствие одного единственного предложения в контенте раздела структуры нарушает второе правило структурирования - "На каждом уровне структуры должно быть, как минимум, два предложения ".

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

Листинг 3: правильно сформированная структура, выполняющая правило двух предложений

1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка

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

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

1.1. Подготовка ингредиентов

1.2. Смешивание ингредиентов шипучего напитка

1.3. Подача шипучего напитка

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

Во-вторых, правило двух предложений требует от меня написать текст, который является привлекательным, подробным и целесообразным. При записи в «одно предложение» нередко теряются подробности. И, если не рассматривать афоризмы, текст в «одно предложение» - не самое интересное чтение.

4. Избегайте неоднозначных местоимений

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

Рассмотрим абзац в листинге 4.

Листинг 4: абзац с неоднозначными местоимениями

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать.

Данный абзац выглядит, возможно, несколько комично, но он иллюстрирует некоторые важные точки. Во-первых, абзац пытается поставить вас на место, которое занимает читатель. Читатель желает понять, что происходит, но он незнаком с используемыми терминами. А поскольку термины непонятны, то читатель ощущает себя некомпетентным и потому уязвимым. Читателю нужна новая информация - он или она желает стать умнее. Но читатель также немного беспокоится. Допущение собственной некомпетентности, даже перед самим собой, даже на подсознательном уровне - может быть ему неприятно. Читатель болезненно чувствителен к пониманию представляемого материала. Понятия и слова, которые вы, лицо пишущее, считаете само собой разумеющимися, могут быть полностью чуждыми читателю. Одно плохо объяснённое понятие или одно слово, использованное без надлежащего разъяснения, могут подтолкнуть читателя прекратить чтение.

Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“? О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты? Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке».

Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» - и ваша работа остаётся непрочитанной.

В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» - к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. (См. рис. 1 внизу.)

Рис. 1. Использование неоднозначных местоимений запутывает техническое описание

Решение проблемы простое. Посмотрите листинг 5 внизу. Неоднозначное местоимение удалено. Ясность восстановлена.

Листинг 5: устранение неоднозначных местоимений

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать.

Осторожно! Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство.

5. Ясность = иллюстрации + слова

Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?

Я не удивлюсь, если вы будете немного растеряны. Эта фотография, действительно, озадачивает. Вы знаете все отдельные компоненты, но вам неясно, что они все вместе значат. Такова природа любой иллюстрации. Картинке без слов не хватает контекста.

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

Посмотрите на рис. 2 внизу. Он представляет собой то же самое фото. Но здесь уже нет вопроса, о чём оно.


Рис. 2. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка

Применительно к техническим описаниям я считаю полезным все иллюстрации снабжать пронумерованными описательными надписями.

Не помещайте надписи, содержащие только цифры. Используйте в надписи, как цифры, так и описательный комментарий. Также не допускайте появления изолированных иллюстраций. Изолированной иллюстрацией считается такая, которая расположена в техническом описании, но ссылка на которую в тексте отсутствует.

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

Примечание : глаз привлекают изображения

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

6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример, логическую иллюстрацию и пример

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

Применим это правило для описания понятия элементарной алгебры.

Понятие «транзитивность отношения равенства» представляет собой следующее:

Если A = B и B = C, то A = C;

Теперь приведём логическую иллюстрацию, описывающую это понятие (см. рис. 3).


Рис. 3. Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры

Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения.

Листинг 6: некоторые конкретные примеры транзитивности отношения равенства

  • Если 7 = 3 + 4 и 3 + 4 = 5 + 2, то 7 = 5 + 2;
  • Если 12 + 5 = 7 + 10 и 7 + 10 = 6 + 11, то 12 + 5 = 6 + 11;
  • Если x + y = z и z = 2a, то x + y = 2a.
Таким образом, правило соблюдено. Мы представили понятие «транзитивность отношения равенства», проиллюстрировали его описательным рисунком и подкрепили примерами.

Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является наследование моделей объектов проекта (POM = Project Object Model) в Maven (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие. В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования.

Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов)

Представление наследования POM-файла

POM -файл является XML-файлом, используемым для описания Maven -проекта и для работы с этим проектом. Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент В вашем POM-файле, чтобы задать родительский POM-файл, из которого должно произойти наследование настроек.

Рис. 4 ниже показывает иерархию некоторого условного проекта, являющуюся примером задания мастер-файла РОМ, из которого другие РОМ-файлы могут наследовать общие настройки.


Рис. 4. Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек

Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента Для наследования настроек из stooges-project.


Рис. 5. Использование элемента Для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла


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

Итак, если требуется предельно ясно представить какое-то понятие, то необходимо включить в текст иллюстрации и примеры.

7. Не опасайтесь переделок

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

Можно сказать об этой работе, перефразируя известную цитату Томаса Эдисона : «Написание технического текста - это на 10% литературное творчество и на 90% переработка!»

1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего);
2. Добавляю иллюстрации в структуру для каждого понятия;
3. Делаю подписи под иллюстрациями;
4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст;
5. Редактирую, переделываю;
6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании);
7. Снова редактирую работу на основе отзыва рецензента (рецензентов).

  • подготовка документации
    • Добавить метки