Лучшие Пять Ошибок, Которые Компании Делают относительно Технической Документации

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

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

1. Имея пользовательских руководств

Не смеяться. Это может походить на довольно основное абсурдное ошибкой, даже - но это удивительно распространено. Я столкнулся со многими компаниями, которые не обеспечивают пользовательские руководства для их продуктов, или чьи руководства skeletally тонкий или устаревшие годы. Фактически, я оценил бы, что приблизительно половина маленьких машиностроительных компаний, что я столкнулся с падением в эту категорию. (Конечно, каждый редко сталкивается с этой проблемой, покупая стандартное программное обеспечение или бытовую электронику. Среди инженеров, хотя, это - уныло знакомая история).

Я помню, как один инженер сказал мне, почему его компания не предоставляла пользовательским руководствам их продукты. Беззвучными тонами он сказал, Это - потому что мы не делаем денег при письме руководств. Это не прибыльное предприятие, таким образом наше управление не хочет напрасно тратить время на этом раздражаемое выражение ползало в его лицо, тогда он наклонялся ближе и говорил, Мы потеряли очень много клиентов, потому что у нас нет приличной документации. Разговор о том, чтобы быть мелочным, глупым фунтом!

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

2. Имея надлежащую внутреннюю документацию

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

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

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

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

3. Упущение аудитории

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

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

4. Будучи соответственно графический

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

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

5. Борясь за превосходство

Интересно видеть, как программисты и инженеры могут бороться за превосходство во многих аспектах их работы, все же проявить подход полной противоположности когда дело доходит до документации. Кто заботится о формулировке так или иначе? я услышал, что много инженеров говорят. Мы не пишем поэзию или сценарии здесь. Что дела то, что документация должна быть технически точной

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

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

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

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

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

V. Berba Velasco имеет докторантуру в Электротехнике и сгибал его торговлю в течение почти десятилетия. В течение того времени он неоднократно обнаруживал важность хорошего технического письма, и ловушки, которые могут произойти от игнорирования его ценности.