Технічне письмо для початківців - Керівництво AZ з основ технічних блогів

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

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

Давайте зануримось у основи та дізнаємось про те, що ви повинні знати та враховувати, починаючи з технічного письма.

Зміст

У цій статті ми розглянемо:

  • Що таке технічне письмо
  • Переваги технічного письма
  • Необхідні навички технічного письменника
  • Процес технічного письма
  • Платформи для публікації ваших статей
  • Курси технічного письма
  • Форуми та спільноти технічного письма
  • Деякі дивовижні технічні автори, яких слід дотримуватися
  • Заключні слова та посилання

Що таке технічне письмо?

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

А технічний письменник - це той, хто пише ці інструкції, інакше відомі як технічна документація чи навчальні посібники. Це може включати посібники користувача, статті про підтримку в Інтернеті або внутрішні документи для кодерів / розробників API.

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

Переваги технічного письма

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

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

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

Ви також можете заробляти гроші як технічний письменник, допомагаючи організаціям. Ось деякі організації, які платять вам за їх написання, такі як Smashing Magazine, AuthO, Twilio та Stack Overflow.

На додаток до всього цього, ви можете брати участь у спільнотах з відкритим кодом та брати участь у платних програмах з відкритим кодом, таких як Google Season of Docs та Outreachy.

Ви також можете взяти технічне письмо як професію повного робочого дня - багатьом компаніям потрібен хтось із цими навичками.

Необхідні навички, як технічний письменник

Розуміти використання належної англійської мови

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

Вмійте пояснювати речі чітко і просто

Знання того, як реалізувати функцію, не обов’язково означає, що ви можете чітко донести процес до інших.

Для того, щоб бути хорошим викладачем, ви повинні бути співчутливим, вміти викладати або описувати терміни, придатні для вашої аудиторії.

Якщо ви не можете пояснити це шестирічному віку, ви самі цього не розумієте. Альберт Ейнштейн

Володіти деякими навичками письма‌‌

Я вважаю, що письменники створюються, а не народжуються. А навчитися писати можна лише насправді писавши.

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

Тож я закликаю вас почати писати сьогодні. Ви можете розпочати з будь-якої з платформ, перерахованих у цьому розділі, щоб розтягнути свої письмові м’язи.

І звичайно, це також величезна вигода мати певний досвід у технічній галузі.

Процес технічного письма

Проаналізуйте та зрозумійте, хто ваші читачі

Найбільший фактор, який слід враховувати при написанні технічної статті, - це передбачувана / очікувана аудиторія. Це завжди має бути на передньому плані вашого розуму.

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

Ви можете розпочати свою статтю, виклавши всі необхідні передумови. Це забезпечить, щоб ваші читачі мали (або могли отримати) необхідні знання перед тим, як зануритися прямо у вашу статтю.

Ви також можете включити посилання на корисні ресурси, щоб ваші читачі могли отримати необхідну інформацію одним клацанням миші.

Щоб знати, для кого пишеш, ти повинен зібрати якомога більше інформації про те, хто буде використовувати документ.

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

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

Щоб зрозуміти свого читача, поставте собі такі запитання, перш ніж почати писати:

  • Хто мої читачі?
  • Що їм потрібно?
  • Де вони будуть читати?
  • Коли вони будуть читати?
  • Чому вони будуть читати?
  • Як вони будуть читати?

Ці запитання також допомагають вам подумати про досвід читача під час читання вашого письма, про що ми поговоримо далі.

Подумайте про досвід користувача

Користувацький досвід настільки ж важливий у технічному документі, як і будь-де в Інтернеті.

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

Поки ви пишете, постійно відступайте і переглядайте документ так, ніби ви читач. Запитайте себе: чи доступний він? Як ваші читачі будуть цим користуватися? Коли вони будуть ним користуватися? Легко орієнтуватися?

Мета - написати документ, корисний і корисний для читачів.

Сплануйте свій документ

Пам’ятаючи, ким є ваші користувачі, ви зможете потім розробити концепцію та спланувати свій документ.

Цей процес включає ряд кроків, які ми пройдемо зараз.

Проведіть ретельне дослідження теми

Плануючи свій документ, ви повинні дослідити тему, про яку пишете. Існує маса ресурсів, доступних лише для пошуку в Google, щоб ви могли їх споживати та отримати глибшу інформацію.

Не спокушайтеся відкидати чужі твори чи статті та видавати їх як власні, оскільки це плагіат. Скоріше, використовуйте ці ресурси як посилання та ідеї для своєї роботи.

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

Зробіть контур

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

Контур також може допомогти вам визначити, що ви хочете, щоб ваші читачі отримали з документа. І нарешті, він встановлює часову шкалу для завершення вашого написання.

Отримайте відповідну графіку / зображення

Наявність контуру дуже корисно для ідентифікації різних віртуальних допоміжних засобів (інфографіки, GIF-файли, відео, твіти), які потрібно буде вставляти в різні розділи вашого документа.

І це значно полегшить вам процес написання, якщо ви будете тримати цю відповідну графіку під рукою.

Пишіть у правильному стилі

Нарешті, можна починати писати! Якщо ви виконали всі ці кроки, писати має стати набагато простіше. Але вам все-таки потрібно переконатися, що ваш стиль письма відповідає технічному документу.

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

Використовуйте активний голос

Це гарна ідея використовувати активні голоси у своїх статтях, оскільки їх легше читати та розуміти, ніж пасивні.

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

Ось приклад пасивного голосу : кожен веб-розробник повинен читати документацію шість разів на рік.

І ось приклад активного голосу : кожен веб-розробник повинен читати цю документацію 6 разів на рік.

Ретельно підбирайте слова

Вибір слова важливий. Обов’язково використовуйте найкраще слово для контексту. Уникайте надмірного використання займенників, таких як „це“ та „це“, оскільки читач може мати труднощі з визначенням іменників, до яких вони відносяться.

Також уникайте сленгу та вульгарної мови - пам’ятайте, що ви пишете для ширшої аудиторії, чия вдача та культурні нахили можуть відрізнятися від ваших.

Уникайте надмірного жаргону

Якщо ви фахівець у своїй галузі, можна легко використати знайомий вам жаргон, не розуміючи, що він може заплутати інших читачів.

Також слід уникати використання скорочень, яких ви раніше не пояснювали.

Ось приклад :

Менш зрозуміло: PWA справді вважаються майбутнім мультиплатформеного розвитку. Їх наявність як на Android, так і на iOS робить їх додатком майбутнього.

Покращено: Прогресивні веб-програми (PWA) - це справді майбутнє розробки мультиплатформ. Їх наявність як на Android, так і на iOS робить PWA додатком майбутнього.

Використовуйте звичайну мову

Використовуйте менше слів і пишіть так, щоб будь-який читач міг зрозуміти текст. ‌‌ Уникайте великих довгих слів. Завжди намагайтеся пояснити поняття та терміни якомога чіткіше.

Візуальне форматування

Стіну тексту важко прочитати. Навіть найчіткіші вказівки можна загубити в документі, який погано візуально відображає.

Кажуть, малюнок вартий тисячі слів. Це звучить вірно навіть у технічному письмі.

Але не будь-яке зображення гідне технічного документа. Технічну інформацію може бути важко передати лише в тексті. Правильно розміщене зображення або схема можуть пояснити ваше пояснення.

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

По-перше, ось фрагмент блогу без візуальних матеріалів:

Ось фрагмент того самого блогу, але з візуальними елементами:

Додавання зображень до ваших статей робить вміст більш зручним та легшим для розуміння. Окрім зображень, ви також можете використовувати GIF-файли, смайли, вставки (соціальні мережі, код) та фрагменти коду, де це необхідно.

Продумане форматування, шаблони та зображення або схеми також зроблять ваш текст більш корисним для читачів. Ви можете ознайомитися з посиланнями нижче для технічного шаблону для написання від @Bolajiayodeji.

Зробіть ретельний огляд

Хороший текст будь-якого типу не повинен містити орфографічних та граматичних помилок. Ці помилки можуть здатися очевидними, але їх не завжди легко виявити (особливо у великих документах).

Завжди переконайтесь у написанні (знаєте, поставте крапку Is та перекресліть Ts), перш ніж натискати "опублікувати".

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

Де публікувати свої статті

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

Dev.to - це спільнота тисяч техніків, де як письменники, так і читачі мають значне залучення та обмін ідеями та ресурсами.

Hashnode - це моя платформа для ведення блогів із чудовими пільгами, такими як спеціальне картографування доменів та інтерактивна спільнота. Створення блогу на цій платформі також є простим і швидким.

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

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

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

У Hackernoon понад 7000 письменників, і це може стати чудовою платформою для того, щоб почати публікувати свої статті для понад 200000 щоденних читачів у спільноті.

Hacker Noon підтримує письменників, вичитуючи їх статті перед публікацією на платформі, допомагаючи їм уникнути типових помилок.

Курси технічного письма

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

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

Ось декілька курсів технічного письма, які ви можете переглянути:

  • Курс технічного письма від Google (безкоштовно)
  • Курс технічного письма Udemy (платний)
  • Bootcamp технічного письма Hashnode (безкоштовно)

Форуми та спільноти технічного письма

Поодинці ми можемо зробити так мало, разом, ми можемо зробити так багато ~ Хелен Келлер

Бути частиною спільноти чи форуму разом із людьми, які поділяють таку ж пристрасть, як і ви, вигідно. Ви можете отримати відгук, виправлення, поради та навіть навчитися деяким підказам щодо стилів від інших авторів спільноти.

Ось кілька спільнот та форумів, до яких ви можете приєднатися:

  • Хешнод
  • Для розробників
  • Світ технічного письма
  • Форум технічних письменників
  • Напишіть форум "Документи"

Деякі дивовижні технічні автори, яких слід дотримуватися

У своїй технічній подорожі я приїжджав і слідував за деякими видатними письменниками-техніками, чия письменницька подорож, послідовність та стиль надихають мене.

Це письменники, на яких я розглядаю і вважаю віртуальними наставниками з питань технічного письма. Іноді вони опускають технічні поради щодо написання, які я вважаю корисними і я багато чому навчився.

Ось деякі з цих авторів (гіперпосилання з їх ручками Twitter):

  • Квінсі Ларсон
  • Едідіонг Асікпо
  • Каталінова яма
  • Вікторія Ло
  • Боладжі Айодеджі
  • Амрута Ранаде
  • Кріс Бонгерс
  • Колбі Файок

Заключні слова

Вам не потрібен науковий ступінь з технічного письма, щоб почати викладати технічний зміст. Ви можете почати писати у своєму особистому блозі та загальнодоступних сховищах GitHub, будуючи своє портфоліо та отримуючи практичний досвід.

Дійсно - Просто починайте писати.

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

Чи є програма, якою ви любите користуватися, але її документація написана погано? Напишіть своє і поділіться ним в Інтернеті для зворотного зв’язку. Ви також можете швидко налаштувати свій блог на hashnode і почати писати.

Ви вчитесь писати, пишучи, читаючи та думаючи про те, як письменники створювали своїх героїв та вигадували свої історії. Якщо ви не читач, навіть не думайте про те, щоб бути письменником. - Жан М. Ауель

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

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

Не можу дочекатися перегляду ваших технічних статей!

Список літератури

Вступ до технічного письма‌‌

Як структурувати технічну статтю‌‌

Розуміння своєї аудиторії, чому і як

TemplateШаблон технічного письма

Сподіваюсь, це було корисно. Якщо так, підпишіться на мене у Twitter та повідомте мене!