Техническое письмо для нетехнических специалистов

Несколько уловок, которые помогут справиться с отставанием в документации

Я специально сделал нечеткое название. Вы пишете для нетехнических специалистов? Или вы нетехнический человек, которому нужно писать технические вещи?

На самом деле это не имеет значения.

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

Не чувствуете себя на 100% уверенным? Вот несколько уловок, которые помогут вам в кратчайшие сроки справиться с невыполненной документацией.

Техническое письмо не должно быть скучным.

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

Говорите со своей реальной аудиторией.

Это не ваши личные заметки, так что имейте это в виду. Но это тоже не ваша диссертация. За самую экстравагантную документацию никто не вручает призов.

Ваша цель - получить сложную информацию и сделать ее легкой для понимания. Вот и все.

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

Дизайн, форматирование и организация важны.

Помните: вы пытаетесь сделать так, чтобы людям было проще понять.

  • Документы должны иметь предсказуемые названия. Никаких странных сокращений, ни untitled-v2-final_FINAL, ни doc1-revision.docx.pdf и т. Д.
  • Скриншоты (если они используются) должны быть целенаправленными, четкими и помеченными.
  • Стратегически используйте заголовки, подзаголовки и основной текст. Таблицы содержания не создаются сами по себе, если вы не используете заголовки! 😉
  • Текст должен быть разбит на абзацы или списки, которые легко усваиваются.

Обдумайте цель создаваемого документа.

Действительно ли нам нужен этот документ? Для чего это? Кто это для? Это должен быть один большой документ или несколько меньших документов? Подумайте об этом, прежде чем начать писать, и в конечном итоге вы сэкономите много времени.

Вы знаете, о чем пишете?

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

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