Техническо писане за начинаещи - Ръководство на AZ за основи на техническия блог

Ако обичате писането и технологиите, техническото писане може да бъде подходяща кариера за вас. Това е и нещо друго, което можете да направите, ако обичате технологиите, но не искате да кодирате през целия ден.

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

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

Съдържание

В тази статия ще разгледаме:

  • Какво е техническо писане
  • Предимства на техническото писане
  • Необходими умения за технически писател
  • Техническият процес на писане
  • Платформи за публикуване на вашите статии
  • Курсове по техническо писане
  • Форуми и общности за техническо писане
  • Някои невероятни технически писатели, които да следвате
  • Заключителни думи и справки

Какво е техническо писане?

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

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

Техническият писател комуникира по начин, който представя техническа информация, така че читателят да може да използва тази информация по предназначение.

Предимства на техническото писане

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

Това е чудесно, защото с всеки нов технически документ, който изследвате и пишете, ще станете експерт по този въпрос.

Техническото писане също ви дава по-добро усещане за съпричастност на потребителите. Помага ви да обърнете повече внимание на това, което чувстват читателите или потребителите на даден продукт, а не на това, което мислите.

Можете също така да печелите пари като технически писател, като допринасяте за организации. Ето някои организации, които ви плащат, за да пишете за тях, като Smashing Magazine, AuthO, Twilio и Stack Overflow.

В допълнение към всичко това можете да допринесете за общности с отворен код и да участвате в платени програми с отворен код като Google Season of Docs и Outreachy.

Можете също така да се заемете с техническо писане като професия на пълен работен ден - много компании се нуждаят от някой с тези умения.

Необходими умения като технически писател

Разберете използването на подходящ английски език

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

Умейте да обяснявате нещата ясно и просто

Знанието как да внедрите функция не означава непременно, че можете ясно да съобщавате процеса на другите.

За да бъдеш добър учител, трябва да бъдеш съпричастен, със способността да преподаваш или описваш термини по начини, подходящи за предвидената ти аудитория.

Ако не можете да го обясните на шестгодишно дете, вие сами не го разбирате. Алберт Айнщайн

Притежавайте някои умения за писане‌‌

Вярвам, че писателите се създават, а не се раждат. И можете да се научите как да пишете, като всъщност пишете.

Може би никога няма да разберете, че го имате в себе си, за да пишете, докато не сложите писалката на хартия. И има само един начин да разберете дали имате някакви умения за писане, и това е чрез писане.

Затова ви насърчавам да започнете да пишете днес. Можете да изберете да започнете с някоя от платформите, които изброих в този раздел, за да разтегнете мускулите си за писане.

И разбира се, огромна полза е и да имате известен опит в техническа област.

Техническият процес на писане

Анализирайте и разберете кои са вашите читатели

Най-големият фактор, който трябва да имате предвид, когато пишете техническа статия, е вашата предвидена / очаквана аудитория. Винаги трябва да е на преден план в ума ви.

Един добър технически писател пише въз основа на контекста на читателя. Като пример , да предположим, че пишете статия, насочена към начинаещи. Важно е да не се предполага, че те вече знаят определени понятия.

Можете да започнете статията си, като посочите всички необходими предпоставки. Това ще гарантира, че вашите читатели имат (или могат да придобият) знанията, от които се нуждаят, преди да се потопят директно във вашата статия.

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

За да знаете за кого пишете, трябва да съберете възможно най-много информация за това кой ще използва документа.

Важно е да знаете дали вашата аудитория има опит в тази област, дали темата е напълно нова за нея, или те попадат някъде между тях.

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

За да разберете читателя си, задайте си следните въпроси, преди да започнете да пишете:

  • Кои са моите читатели?
  • Какво им трябва?
  • Къде ще четат?
  • Кога ще четат?
  • Защо ще четат?
  • Как ще четат?

Тези въпроси също ви помагат да мислите за опита на вашия читател, докато четете писането си, за което ще говорим повече сега.

Помислете за потребителския опит

Потребителският опит е също толкова важен в техническия документ, колкото и навсякъде в мрежата.

След като вече знаете своята аудитория и нейните нужди, имайте предвид как самият документ обслужва техните нужди. Толкова е лесно да се игнорира как читателят всъщност ще използва документа.

Докато пишете, непрекъснато отстъпвайте и гледайте документа, сякаш сте читател. Задайте си въпроса: Достъпен ли е? Как вашите читатели ще го използват? Кога ще го използват? Лесно ли е да се ориентирате?

Целта е да напишете документ, който е едновременно полезен и използваем от вашите читатели.

Планирайте документа си

Имайки предвид кои са вашите потребители, след това можете да концептуализирате и планирате документа си.

Този процес включва редица стъпки, които ще преминем сега.

Проведете задълбочени изследвания по темата

Докато планирате документа си, трябва да проучите темата, за която пишете. Има тонове ресурси, които можете да консумирате и да получите по-задълбочена представа само за търсене с Google.

Не се изкушавайте да повдигнете чужди произведения или статии и да ги предадете като свои, тъй като това е плагиатство. По-скоро използвайте тези ресурси като справки и идеи за вашата работа.

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

Направете контур

Очертаването на съдържанието на вашия документ, преди да го разширите, ви помага да пишете по-фокусирано. Освен това ви позволява да организирате мислите си и да постигнете целите си за писане.

Контур също може да ви помогне да определите какво искате вашите читатели да извлекат от документа. И накрая, той установява график за завършване на вашето писане.

Вземете подходящи графики / изображения

Наличието на контур е много полезно при идентифицирането на различните виртуални помощни средства (инфографика, gif, видеоклипове, туитове), които ще трябва да вградите в различни раздели на вашия документ.

И много ще улесни процеса на писане, ако държите тези подходящи графики под ръка.

Пишете в правилния стил

И накрая, можете да започнете да пишете! Ако сте изпълнили всички тези стъпки, писането трябва да стане много по-лесно. Но все пак трябва да се уверите, че стилът ви на писане е подходящ за технически документ.

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

Използвайте Active Voice

Добре е да използвате активни гласове във вашите статии, тъй като е по-лесно да се чете и разбира, отколкото пасивният глас.

Активен глас означава, че субектът на изречението е този, който активно извършва действието на глагола. Страдателен залог означава, че има предмет е получателят на глагол за действие .

Ето пример за пасивен глас : Документацията трябва да се чете шест пъти годишно от всеки уеб разработчик.

И ето пример за активен глас : Всеки уеб разработчик трябва да чете тази документация 6 пъти годишно.

Изберете внимателно думите си

Изборът на дума е важен. Уверете се, че използвате най-добрата дума за контекста. Избягвайте да злоупотребявате със местоимения като „it“ и „this“, тъй като читателят може да има затруднения при идентифицирането на кои съществителни се отнасят.

Избягвайте също жаргон и просташки език - не забравяйте, че пишете за по-широка аудитория, чието разположение и културни наклонности могат да се различават от вашите.

Избягвайте прекомерния жаргон

Ако сте експерт във вашата област, може да е лесно да използвате жаргон, с който сте запознати, без да осъзнавате, че може да обърква другите читатели.

Също така трябва да избягвате да използвате съкращения, които не сте обяснявали преди.

Ето пример :

По-малко ясно: PWA наистина се считат за бъдещето на многоплатформеното развитие. Наличието им както на Android, така и на iOS ги прави приложение на бъдещето.

Подобрено: Прогресивните уеб приложения (PWA) наистина са бъдещето на мултиплатформеното развитие. Наличието им както на Android, така и на iOS прави PWAs приложението на бъдещето.

Използвайте обикновен език

Използвайте по-малко думи и пишете по начин, така че всеки читател да може да разбере текста. ‌‌ Избягвайте големи дълги думи. Винаги се опитвайте да обяснявате понятия и термини по възможно най-ясния начин.

Визуално форматиране

Стена от текст е трудна за четене. Дори най-ясните инструкции могат да бъдат загубени в документ, който има лошо визуално представяне.

Казват, че една снимка струва хиляда думи. Това звучи вярно дори в техническото писане.

Но не просто всяко изображение е достойно за технически документ. Техническата информация може да бъде трудна за предаване само в текст. Добре поставеното изображение или диаграма могат да изяснят вашето обяснение.

Хората също обичат визуалните изображения, така че помага да ги вмъкнете на правилните места. Помислете за изображенията по-долу:

Първо, ето фрагмент от блог без визуални елементи:

Ето фрагмент от същия блог, но с визуални ефекти:

Добавянето на изображения към вашите статии прави съдържанието по-свързано и по-лесно за разбиране. В допълнение към изображенията можете да използвате GIF, емоджи, вграждания (социални медии, код) и кодови фрагменти, когато е необходимо.

Замисленото форматиране, шаблони и изображения или диаграми също ще направят текста ви по-полезен за вашите читатели. Можете да разгледате препратките по-долу за технически шаблон за писане от @Bolajiayodeji.

Направете внимателен преглед

Доброто писане от всякакъв вид не трябва да съдържа правописни и граматически грешки. Тези грешки може да изглеждат очевидни, но не винаги е лесно да ги забележите (особено в дълги документи).

Винаги проверявайте двукратно правописа си (знаете, поставете точките си Is и пресечете Ts), преди да натиснете „публикуване“

Има редица безплатни инструменти като Grammarly и приложението Hemingway, които можете да използвате, за да проверите за граматика и правописни грешки. Можете също така да споделите проект на статията си с някого, който да бъде коригиран преди публикуването.

Къде да публикувате статиите си

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

Dev.to е общност от хиляди техници, където както писателите, така и читателите получават смислено участие и споделят идеи и ресурси.

Hashnode е моята платформа за водене на блогове със страхотни предимства като персонализирано картографиране на домейн и интерактивна общност. Създаването на блог на тази платформа също е лесно и бързо.

freeCodeCamp има много голяма общност и обхват на аудиторията и е чудесно място за публикуване на вашите статии. Ще трябва обаче да кандидатствате, за да пишете за публикуването им с някои предишни образци за писане.

Вашата кандидатура може да бъде приета или отхвърлена, но не се обезсърчавайте. Винаги можете да кандидатствате отново по-късно, когато се подобрите, и кой знае? Можеш да бъдеш приет.

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

Hackernoon има над 7000 писатели и може да бъде чудесна платформа за вас да започнете да публикувате своите статии пред над 200 000 ежедневни читатели в общността.

Hacker Noon подкрепя писателите, като коригира статиите им, преди да ги публикува на платформата, като им помага да избегнат често срещани грешки.

Курсове по техническо писане

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

Посещаването на курс по техническо писане ще ви помогне да преминете през всяко нещо, което трябва да научите, а също така може да ви даде значителен стимул за увереност, за да започнете писателското си пътуване.

Ето някои технически курсове за писане, които можете да проверите:

  • Курс за техническо писане на Google (безплатен)
  • Курс за техническо писане Udemy (платен)
  • Bootcamp за техническо писане на Hashnode (безплатно)

Форуми и общности за техническо писане

Сами можем да направим толкова малко, заедно, можем да направим толкова много ~ Хелън Келър

Да бъдеш част от общност или форум заедно с хора, които споделят същата страст като теб, е от полза. Можете да получите обратна връзка, корекции, съвети и дори да научите някои съвети за стил от други писатели в общността.

Ето няколко общности и форуми, към които да се присъедините:

  • Hashnode
  • Dev.to
  • Технически писателски свят
  • Форум за технически писатели
  • Напишете форума за документи

Някои невероятни технически писатели, които да следвате

По време на моето техническо писателско пътешествие дойдох и последвах някои велики технически писатели, чието писателско пътешествие, последователност и стил ме вдъхновяват.

Това са авторите, на които се надявам и ги считам за виртуални ментори по техническо писане. Понякога изпускат технически съвети за писане, които намирам за полезни и от които съм научил много.

Ето някои от тези писатели (хипервръзки с техните twitter дръжки):

  • Куинси Ларсън
  • Edidiong Asikpo
  • Каталинска яма
  • Виктория Ло
  • Боладжи Айодеджи
  • Амрута Ранаде
  • Крис Бонгърс
  • Колби Файок

Заключителни думи

Не е необходима диплома по техническо писане, за да започнете да излагате техническо съдържание. Можете да започнете да пишете в личния си блог и публични хранилища на GitHub, докато изграждате портфолиото си и придобивате практически опит.

Наистина - Просто започнете да пишете.

Практикувайте, като създавате нови документи за съществуващи програми или проекти. В GitHub има редица проекти с отворен код, които можете да проверите и да добавите към тяхната документация.

Има ли приложение, което обичате да използвате, но документацията му е зле написана? Напишете своя собствена и я споделете онлайн за обратна връзка. Можете също така бързо да настроите вашия блог на hashnode и да започнете да пишете.

Научавате се да пишете, като пишете, и като четете и мислите как писателите са създавали своите герои и са измисляли своите истории. Ако не сте читател, дори не мислете да сте писател. - Жан М. Ауел

Техническите писатели винаги се учат . Потапяйки се в нови предметни области и получавайки външна обратна връзка, добрият писател не спира да усъвършенства своя занаят.

Разбира се, добрите писатели са и ненаситни читатели. Чрез преглед на много четени или използвани документи, вашето собствено писане определено ще се подобри.

Нямам търпение да видя техническите ви статии!

Препратки

Въведение в техническото писане‌‌

Как да структурирам техническа статия‌‌

Разбиране на вашата аудитория, защо и как

TemplateТехнически шаблон за писане

Надявам се това да е било полезно. Ако е така, последвайте ме в Twitter и ме уведомете!