Як писати технічну документацію

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

Розглянемо всі тут, щоб не перегортати книжку цілком.

Як писати «прозорий» і зрозумілий текст технічної документації взагалі?

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

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

Програмний засіб являє собою сукупність програми і супутньої їй документації, тому понимаемость програми цілком застосовна як до програмної документації, так і до технічної документації взагалі.

Про понимаемости керівництва. Мова в книзі йде про керівництво користувача. а будь-яке керівництво є набором інструкцій і завдання його - довести (а не донести. як нині зволить виражатися наш доморощений політичний і телевізійний «бомонд») і до піонера і до пенсіонера покрокові шляху досягнення єдиного необхідного результату. Зазначений спосіб викладу текстів «взагалі» дуже навіть можна застосувати в нашому випадку. І ніякого розуміння користувачем усіляких логічних концепцій керівництва зовсім і не потрібно.

Як писати структурований текст?

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

У житті трапляється багато чого цікавого. Дуже часто доводиться відбиватися від публіки, яка прагне самоствердитися за чужий рахунок, від свого роду тролів, тільки не мережевих, а живих і реальних. Витівки цих малоприємних людей по відношенню до добре структурованого тексту не проходять по визначенню

Питання перше: «Що написано у вступній фразі?» Відповідь: «Змінні AuthorIT призначені:»;
Питання друге: «Що написано в першому пункті перерахування?» Відповідь: «. для зберігання фрагментів тексту, елементів графіки і т.д. »;
Питання третє: «Так для чого призначені змінні AuthorIT? Прочитайте вступну фразу і перший пункт перерахування одним реченням »
.
І останнє питання (який нині добиває удар): «ЩО-БУЛО-Незрозуміло ?!»

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

Як писати неструктурований текст?

Про користь впровадження в техдокументації автентичних текстів ГОСТів та інших нормативних документів

Напевно, наведений фрагмент книги пояснювати словами і не треба. Краще розповісти цікавий випадок з життя.

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

Спочатку вирішено було відмовитися, але дуже вже просили. Буквально питання життя і смерті. Чому б не розробити, якщо так воно є? Досвіду проведення різних видів випробувань у «Технічної документації» більш ніж достатньо.

Взялися, помучилися тижнів зо два, зібрали інформацію, проконсультувалися, відшукали нормативні документи по предметної області - з завданням впоралися. І тут-то замовники, які не вирішувалися самі взятися за цю роботу, відчули себе «експертами».

Власне «експертиза» тривала не більше десяти хвилин. За словами очевидця (очевидиці): «. цей ( «експерт») б'ється в істериці і кричить, що він - кандидат наук, а цей (розробник) ввічливо посміхається і тицяє йому пальцем в виноски з ГОСТірованнимі визначеннями термінів і в список використаних стандартів. »

Навколишні повеселилися від щирого серця. Зауважимо, що в інтересах цього ж замовника згодом була розроблена ще одна ПМ, тільки вже більш складних механічних випробувань. але ідеї про проведення її експертизи чомусь ні в кого більше не виникло.

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