- Контакты ООО «Техническая документация»

Заказать услуги ООО «Техническая документация» можно по эл. почте admin @ tdocs . su (без пробелов), по тел. 8-910-468-09-28 или в форме Контакты.

Как писать техническую документацию?

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

Создан 29.03.2014 16:37:21

- Как писать техническую документацию?

Существует множество нормативных документов, таких как ГОСТ 2.105, ГОСТ 19.106, ГОСТ 28195, ГОСТ 7.32, ГОСТ 8.417 и других основополагающих стандартов, регламентирующих требования к текстовым документам, к их структуре, содержанию, содержимому, построению, стилю изложения, оформлению, к критериям оценки качества, см. Качество технической документации, к сокращениям физических величин. Смысл и важность их применения детально расписаны в подразделе 6.1.3.1 книги Автоматизация разработки технической документации с применением AuthorIT. Учебное пособие.

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

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

Смотрите:
Как писать «прозрачный» и понимаемый текст технической документации вообще?
Как писать структурированный текст?
Как писать неструктурированный текст?
О пользе внедрения в техдокументацию аутентичных текстов ГОСТов и иных нормативных документов
Выводы

Как писать «прозрачный» и понимаемый текст технической документации вообще?

- Изложение текста вообще

Основная идея изложения текста «вообще» изображена на рисунке. Теперь же, как говорят военные, все сказанное поясним словами: желательно, чтобы текст был структурированным, а не планарным, преобладающим в классической отечественной литературе. Под «планарным» понимаем плоский текст (от лат. planus плоский, ровный).

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

Теперь о понимаемости. Понимаемость есть «Совокупность свойств программного средства, характеризующая затраты усилий пользователя на понимание логической концепции этого программного средства. Примечание - Под логической концепцией подразумеваются основополагающие понятия, принципы и соглашения, придающие системе правил работы пользователя с программным средством согласованный и обоснованный характер и позволяющие логически точно определять конкретное назначение и содержание этих правил [из п. 3.1 Прил. 2 ГОСТ 28806-90]»

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

О понимаемости руководства. Речь в книге идет о руководстве пользователя, а любое руководство является набором инструкций и задача его - довести (а не донести, как нынче изволит выражаться наш доморощенный политический и телевизионный «бомонд») и до пионера и до пенсионера пошаговые пути достижения единого требуемого результата. Указанный способ изложения текстов «вообще» очень даже применим в нашем случае. И никакого понимания пользователем всяческих логических концепций руководства вовсе и не требуется.

Как писать структурированный текст?

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

- Изложение структурированного текста

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

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

  1. Вопрос первый: «Что написано во вводной фразе?» Ответ: «Переменные AuthorIT предназначены:»;
  2. Вопрос второй: «Что написано в первом пункте перечисления?» Ответ: «...для хранения фрагментов текста, элементов графики и т.д.»;
  3. Вопрос третий: «Так для чего предназначены переменные AuthorIT? Прочтите вводную фразу и первый пункт перечисления одним предложением»
  4. ...
  5. И последний вопрос (добивающий удар): «ЧТО-БЫЛО-НЕПОНЯТНО?!»

Вот так структурированный текст становится прозрачным, защищенным и, если угодно, насильственно понятным. Оппоненту попросту нечего возразить, он загнан в угол и сидит (по меткому высказыванию г-на Лукашенко) как мышь под веником.

Как писать неструктурированный текст?

- Изложение неструктурированного текста

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

О пользе внедрения в техдокументацию аутентичных текстов ГОСТов и иных нормативных документов

- Политика и идеология проектирования

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

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

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

Поначалу решено было отказаться, но очень уж просили. Буквально вопрос жизни и смерти. Почему бы не разработать, коль так обстоит дело? Опыта проведения различных видов испытаний у «Технической документации» более чем достаточно.

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

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

Окружающие повеселились от всей души. Заметим, что в интересах этого же заказчика впоследствии была разработана еще одна ПМ, только уже более сложных механических испытаний, но идеи о проведениии ее экспертизы почему-то ни у кого больше не возникло...

Выводы

ПИШИТЕ ТЕХНИЧЕСКУЮ ДОКУМЕНТАЦИЮ ПРАВИЛЬНО - и да будит вам всем щщясьте - Ржунимагу! (смайл)

- Контакты ООО «Техническая документация»

Заказать услуги ООО «Техническая документация» можно по эл. почте admin @ tdocs . su (без пробелов), по тел. 8-910-468-09-28 или в форме Контакты.

Copyright © ООО «Техническая документация» 2016. Заимствуйте наши материалы с блеском!
При цитировании на своих ресурсах наших материалов используйте активные ссылки на них.