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

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

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

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

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

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

Рассмотрим их здесь, чтобы не перелистывать книжку целиком. Разработка 3d-моделей, КД, техпроцессов, УП

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Выводы

ПИШИТЕ ТЕХНИЧЕСКУЮ ДОКУМЕНТАЦИЮ ПРАВИЛЬНО - и да будит вам всем щщясьте 🤣