Как писать техническую документацию? Ее содержимое — тексты? Как тексты техдокументации вообще, так и любые технические публикации, от журнальных статей до докторских диссертаций? Простые и эффективные способы, позволяющие писать тексты понятными, без применения каких–либо буржуйских технологий описания, удобочитаемыми и заведомо выдерживающими как самую жесткую и обоснованную критику, так и беспардонные, беспочвенные и технически не обоснованные заявления оппонентов. Редакция от 26.09.2024.
Создан 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. С таким оппонентом расправиться очень легко, если он, конечно, умеет читать (хотя бы по складам):
- Вопрос первый: «Что написано во вводной фразе?» Ответ: «Переменные AuthorIT предназначены:»;
- Вопрос второй: «Что написано в первом пункте перечисления?» Ответ: «...для хранения фрагментов текста, элементов графики и т.д.»;
- Вопрос третий: «Так для чего предназначены переменные AuthorIT? Прочтите вводную фразу и первый пункт перечисления одним предложением»;
- ...
- И последний вопрос (добивающий удар): «ЧТО–БЫЛО–НЕПОНЯТНО?!»
Вот так структурированный текст становится прозрачным, защищенным и, если угодно, насильственно понятным. Оппоненту попросту нечего возразить, он загнан в угол и сидит (по меткому высказыванию г–на Лукашенко) как мышь под веником.
Как писать неструктурированный текст?
Если по каким–либо причинам четко структурировать текст не представляется возможным, то разумнее всего изложить его так, чтобы появился «эффект следования», как изображено на рисунке выше. Комментировать, наверное, нечего.
О пользе внедрения в техдокументацию аутентичных текстов ГОСТов и иных нормативных документов
Внедрение в техдокументацию аутентичных текстов ГОСТов и иных нормативных документов — замечательный способ поставить оппонента на колени, только оппонент в данном случае представляется не глупым наглым троллем из серии «креатив — дрянь, автор — козел», а товарищем, мнящим себя экспертом в предметной области.
Наверное, приведенный фрагмент книги объяснять словами и не надо. Лучше поведать занимательный случай из жизни.
Однажды, в студеную зимнюю пору — а мороз был под тридцать — поступил заказ на разработку программы и методики испытаний оборудования измерения расхода и контроля качества газа. Причем заказ пришел от самих газовиков...
Поначалу решено было отказаться, но очень уж просили. Буквально вопрос жизни и смерти. Почему бы не разработать, коль так обстоит дело? Опыта проведения различных видов испытаний у «Технической документации» более чем достаточно.
Взялись, помучились недельки две, собрали информацию, проконсультировались, отыскали нормативные документы по предметной области — с задачей справились. И тут–то заказчики, которые не решались сами взяться за эту работу, почувствовали себя «экспертами».
Собственно «экспертиза» продлилась не более десяти минут. Со слов очевидца (очевидицы): «...этот («эксперт») бьется в истерике и кричит, что он — кандидат наук, а этот (разработчик) вежливо улыбается и тычет ему пальцем в сноски с ГОСТированными определениями терминов и в список использованных стандартов...»
Окружающие повеселились от всей души. Заметим, что в интересах этого же заказчика впоследствии была разработана еще одна ПМ, только уже более сложных механических испытаний, но идеи о проведениии ее экспертизы почему–то ни у кого больше не возникло...
Выводы
ПИШИТЕ ТЕХНИЧЕСКУЮ ДОКУМЕНТАЦИЮ ПРАВИЛЬНО — и да будит вам всем щщясьте 🤣
