Советы технического писателя

Как технический писатель, меня часто просят написать о вещах, о которых я мало что знаю. Пока что.

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

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

Но не всегда бывает так легко. С учетом сложных тем и приближающихся сроков, как мне удается выучить то, что мне нужно, даже если я не изучил предварительные условия?

1. Найдите точку входа. Любая точка входа.

Допустим, вы хотите выучить n. Вы ничего не знаете о n.

Но вы кое-что знаете о m и слышали о o раньше. Вы много знаете о h и t и являетесь экспертом в a.

Это ваши точки входа.

Я буду использовать программирование в качестве примера, но это применимо во всех сферах.

Вы решаете, что хотите изучить Python. Вы ничего не знаете о Python и никогда раньше не программировали. Вы гуглите "Learn Python" и находите кучу документации, которую вы (пока) не понимаете, и несколько статей о Data Science на Medium.

Наука о данных. Хм. Данные. Однажды вы прошли курс по статистике и сдали его. Вы в значительной степени являетесь экспертом в Excel. Вы работаете с большими наборами данных весь день на работе.

Вы копаете немного глубже и ... эй, оказывается, Python - мощный инструмент для науки о данных и анализа данных.

Это ваша точка входа.

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

2. Научитесь задавать правильные вопросы.

Вы можете спросить живых людей или Google, но независимо от того, что вы изучаете, у вас будут вопросы.

Если вы не знаете, чего не знаете… вы не сможете задавать правильные вопросы.

Это означает, что вам нужно время, чтобы познакомиться с отраслевой лексикой. Задавать правильные вопросы обычно означает использовать правильную терминологию, потому что никто не поймет: «Вы знаете эту штуку, например, когда вы заходите в консоль, и она говорит какое-то сообщение об ошибке, да, как это работает?»

Выясните, что вам нужно спросить, прежде чем спрашивать, иначе вы рискуете получить неправильные ответы.

3. Работайте в обратном направлении.

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

Я погуглил. Я читаю. Я смотрел видео. Я спросил у профильных экспертов. Нада. Неа. Это пролетело над моей головой.

Пришлось работать задом наперед.

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

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

Вы начинаете учиться и понимаете, что даже не знаете, что такое jQuery. Ну, погоди. Вы уже изучали JavaScript? Нет. Вы понимаете, что вам это может понадобиться. Вы копаетесь, но потом читаете что-то о том, как снова поместить исходный код сценария в ... какой файл? HTML? Нет, никогда об этом не слышал!, - говорите вы себе.

Итак, вы прошли путь от центра проблемы к внешнему углу и поняли, с чего начать.

4. Выясните, как вы лучше всего учитесь.

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

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

Знание того, как вы учитесь, является неотъемлемой частью обучения тому, как учиться.

В противном случае вы просто обнаружите, что тратите время на уловки и уловки, которые не работают.

Чтобы понять, как вы учитесь, нужно найти ресурсы, которые вам понятны, и использовать их стратегически.

5. Выговорите это.

Да, если нужно, поговорите с собой. Раздумывайте сами и задавайте себе хорошие вопросы. Вместо того, чтобы быть худшим критиком самого себя, станьте самым большим поклонником самого себя. Вы знаете себя лучше, чем кто-либо другой… поэтому, когда вы наезжаете на кочку на дороге, говорите об этом.

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

Так? Обсуди это с самим собой.

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

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

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

Вы можете поговорить с собой о большинстве проблем.

Когда вы изучаете что-то сложное, всегда задавайте себе два вопроса: «Есть ли в этом смысл?» и "Есть ли другие возможности?"

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

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

Вы просто можете обнаружить, что уже знаете больше, чем ожидали.

Эта история опубликована в The Startup, крупнейшем предпринимательском издании Medium, за которым следят +436 678 человек.

Подпишитесь, чтобы получать наши главные новости здесь.