Tehniskā rakstīšana iesācējiem - AZ ceļvedis tehnisko emuāru veidošanas pamatiem

Ja jums patīk rakstīšana un tehnoloģijas, tehniskā rakstīšana varētu būt jums piemērota karjera. Tas ir arī kaut kas cits, ko jūs varat darīt, ja jums patīk tehnoloģijas, bet jūs patiešām nevēlaties kodēt visas dienas garumā.

Tehniskā rakstīšana varētu būt domāta arī jums, ja jums patīk mācīties, mācot citus, dodot ieguldījumu atvērtā pirmkoda projektos un arī citiem mācot, kā to izdarīt, vai būtībā jums patīk vienkārši izskaidrot sarežģītus jēdzienus, izmantojot savu rakstu.

Iegremdēsimies pamatos un uzzināsim par to, kas jums jāzina un jāņem vērā, sākot darbu ar tehnisko rakstīšanu.

Satura rādītājs

Šajā rakstā mēs aplūkosim:

  • Kas ir tehniskā rakstīšana
  • Tehniskās rakstīšanas priekšrocības
  • Nepieciešamās prasmes, lai būtu kā tehniskais rakstnieks
  • Tehniskās rakstīšanas process
  • Jūsu rakstu publicēšanas platformas
  • Tehniskās rakstīšanas kursi
  • Tehniskās rakstīšanas forumi un kopienas
  • Daži apbrīnojami tehniskie autori, kuriem sekot
  • Nobeiguma vārdi un atsauces

Kas ir tehniskā rakstīšana?

Tehniskā rakstīšana ir māksla sniegt uz detaļām orientētas instrukcijas, lai palīdzētu lietotājiem saprast noteiktu prasmi vai produktu.

Un tehniskais autors ir tas, kurš raksta šīs instrukcijas, citādi dēvētas par tehnisko dokumentāciju vai konsultācijām. Tas var ietvert lietotāja rokasgrāmatas, tiešsaistes atbalsta rakstus vai iekšējos dokumentus kodētājiem / API izstrādātājiem.

Tehniskais autors sazinās tādā veidā, lai sniegtu tehnisko informāciju, lai lasītājs varētu izmantot šo informāciju paredzētajam mērķim.

Tehniskās rakstīšanas priekšrocības

Tehniskie autori mācās visu mūžu. Tā kā darbs ir saistīts ar sarežģītu jēdzienu paziņošanu vienkāršā un nepārprotamā veidā, jums ir labi jāpārzina joma, par kuru rakstāt. Vai arī esiet gatavs par to uzzināt.

Tas ir lieliski, jo ar katru jaunu tehnisko dokumentu, kuru izpētāt un uzrakstāt, jūs kļūsiet par šīs tēmas ekspertu.

Tehniskā rakstīšana arī ļauj labāk izprast lietotāju empātiju. Tas palīdz vairāk pievērst uzmanību tam, ko jūtas produkta lasītāji vai lietotāji, nevis tam, ko jūs domājat.

Jūs varat arī nopelnīt naudu kā tehniskais autors, sniedzot ieguldījumu organizācijās. Šeit ir dažas organizācijas, kas maksā jums par to rakstīšanu, piemēram, žurnāls Smashing, AuthO, Twilio un Stack Overflow.

Papildus tam jūs varat dot ieguldījumu atvērtā pirmkoda kopienās un piedalīties apmaksātās atvērtā pirmkoda programmās, piemēram, Google dokumentu sezonā un Outreachy.

Jūs varat arī uzņemties tehnisko rakstīšanu kā pilnas slodzes profesiju - daudziem uzņēmumiem ir vajadzīgs kāds ar šīm prasmēm.

Nepieciešamās prasmes, kas nepieciešamas kā tehniskais rakstnieks

Izprot pareizas angļu valodas lietošanu

Pirms domājat par rakstīšanu, ir nepieciešams labi pārzināt angļu valodu, tās laikus, pareizrakstību un gramatikas pamatus. Jūsu lasītāji nevēlas lasīt rakstu, kas pārņemts ar nepareizu gramatiku un sliktu vārdu izvēli.

Ziniet, kā skaidri un vienkārši izskaidrot lietas

Zinot, kā ieviest funkciju, tas nenozīmē, ka jūs varat skaidri paziņot procesu citiem.

Lai būtu labs skolotājs, jums jābūt iejūtīgam, ar spēju mācīt vai aprakstīt terminus tādā veidā, kas piemērots jūsu paredzētajai auditorijai.

Ja jūs to nevarat izskaidrot sešus gadus vecam bērnam, pats to nesaprotat. Alberts Einšteins

Piemīt dažas rakstīšanas prasmes‌‌

Es uzskatu, ka rakstnieki ir radīti, nevis dzimuši. Uzzināt, kā rakstīt, var tikai rakstot.

Jūs, iespējams, nekad nezināt, ka jums ir rakstīšana, līdz jūs ievietojat pildspalvu uz papīra. Ir tikai viens veids, kā uzzināt, vai jums ir kāda rakstīšanas prasme, un tas ir rakstot.

Tāpēc es iesaku sākt rakstīt jau šodien. Lai izstieptu rakstīšanas muskuļus, varat sākt sākt ar jebkuru no platformām, kuras esmu uzskaitījis šajā sadaļā.

Un, protams, milzīgs ieguvums ir arī zināma pieredze tehniskajā jomā.

Tehniskās rakstīšanas process

Analizējiet un saprotiet, kas ir jūsu lasītāji

Lielākais faktors, kas jāņem vērā, rakstot tehnisku rakstu, ir jūsu paredzētā / paredzamā auditorija. Tam vienmēr vajadzētu būt jūsu prāta priekšplānā.

Labs tehniskais autors raksta, balstoties uz lasītāja kontekstu. Pieņemsim , ka jūs rakstāt rakstu, kas paredzēts iesācējiem. Ir svarīgi neuzskatīt, ka viņi jau zina noteiktus jēdzienus.

Jūs varat sākt savu rakstu, norādot visus nepieciešamos priekšnoteikumus. Tas nodrošinās, ka lasītājiem ir (vai var iegūt) nepieciešamās zināšanas pirms ienirt tieši jūsu rakstā.

Varat arī iekļaut saites uz noderīgiem resursiem, lai lasītāji varētu iegūt nepieciešamo informāciju tikai ar vienu klikšķi.

Lai uzzinātu, kam rakstāt, jums jāapkopo pēc iespējas vairāk informācijas par to, kurš izmantos dokumentu.

Ir svarīgi zināt, vai jūsu auditorijai ir pieredze šajā jomā, vai šī tēma viņiem ir pilnīgi jauna, vai arī viņi atrodas kaut kur pa vidu.

Jūsu lasītājiem būs arī savas cerības un vajadzības. Jums jānosaka, ko lasītājs meklē, kad viņš sāk lasīt dokumentu un ko viņš no tā iegūs.

Lai saprastu lasītāju, pirms sākat rakstīt, uzdodiet sev šādus jautājumus:

  • Kas ir mani lasītāji?
  • Kas viņiem vajadzīgs?
  • Kur viņi lasīs?
  • Kad viņi lasīs?
  • Kāpēc viņi lasīs?
  • Kā viņi lasīs?

Šie jautājumi arī palīdz domāt par lasītāja pieredzi lasot jūsu rakstīto, par kuru mēs vairāk runāsim tagad.

Padomājiet par lietotāja pieredzi

Lietotāja pieredze tehniskajā dokumentā ir tikpat svarīga kā jebkur tīmeklī.

Tagad, kad zināt savu auditoriju un viņu vajadzības, paturiet prātā, kā pats dokuments kalpo viņu vajadzībām. Ir tik viegli ignorēt to, kā lasītājs faktiski izmantos dokumentu.

Rakstot nepārtraukti atkāpieties un apskatiet dokumentu tā, it kā jūs būtu lasītājs. Pajautājiet sev: vai tas ir pieejams? Kā lasītāji to izmantos? Kad viņi to izmantos? Vai ir viegli orientēties?

Mērķis ir uzrakstīt dokumentu, kas ir noderīgs lasītājiem un var to izmantot.

Plānojiet savu dokumentu

Paturot prātā, kas ir jūsu lietotāji, varat konceptualizēt un plānot savu dokumentu.

Šis process ietver vairākas darbības, kuras mēs tagad pārvērtīsim.

Veiciet rūpīgu pētījumu par tēmu

Plānojot dokumentu, jums jāpēta tēma, par kuru rakstāt. Ir daudz resursu, kas pieejami tikai Google meklēšanā, lai jūs tos varētu patērēt un iegūt dziļāku ieskatu.

Nav kārdinājums pacelt citu cilvēku darbus vai rakstus un nodot tos kā savus, jo tas ir plaģiāts. Drīzāk izmantojiet šos resursus kā atsauces un idejas savam darbam.

Google pēc iespējas vairāk, iegūstiet faktus un skaitļus no pētījumu žurnāliem, grāmatām vai ziņām un apkopojiet pēc iespējas vairāk informācijas par savu tēmu. Tad jūs varat sākt veidot kontūru.

Izveidojiet kontūru

Dokumenta satura izklāsts pirms tā paplašināšanas palīdz rakstīt mērķtiecīgāk. Tas arī ļauj jums sakārtot savas domas un sasniegt savus rakstīšanas mērķus.

Kontūras var arī palīdzēt jums noteikt, ko vēlaties, lai lasītāji izkļūtu no dokumenta. Un visbeidzot, tas nosaka laika grafiku jūsu rakstīšanas pabeigšanai.

Iegūstiet atbilstošu grafiku / attēlus

Kontūras iegūšana ir ļoti noderīga, lai identificētu dažādus virtuālos palīglīdzekļus (infografikas, gifus, videoklipus, tvītus), kas jums jāiegulda dažādās dokumenta sadaļās.

Un tas ievērojami atvieglos jūsu rakstīšanas procesu, ja šīs attiecīgās grafikas glabāsiet ērti.

Rakstiet pareizajā stilā

Visbeidzot, jūs varat sākt rakstīt! Ja esat pabeidzis visas šīs darbības, rakstīšanai jākļūst daudz vienkāršākai. Bet jums joprojām ir jāpārliecinās, vai jūsu rakstīšanas stils ir piemērots tehniskajam dokumentam.

Rakstam jābūt pieejamam, tiešam un profesionālam. Puķains vai emocionāls teksts nav laipni gaidīts tehniskajā dokumentā. Lai palīdzētu jums saglabāt šo stilu, šeit ir daži galvenie raksturlielumi, kas jums jāattīsta.

Izmantojiet aktīvo balsi

Rakstos ir ieteicams izmantot aktīvās balsis, jo tās ir vieglāk lasīt un saprast nekā pasīvo balsi.

Aktīvās balss nozīmē, ka priekšmets ir teikuma ir viens aktīvi veicot darbību no vārda. Pasīvās balss nozīmē, ka priekšmets ir saņēmējs darbības vārda s darbībā .

Lūk, pasīvās balss piemērs : Katram tīmekļa izstrādātājam dokumentācija ir jālasa sešas reizes gadā.

Un šeit ir aktīvās balss piemērs : katram tīmekļa izstrādātājam šī dokumentācija ir jāizlasa 6 reizes gadā.

Rūpīgi izvēlieties savus vārdus

Vārdu izvēle ir svarīga. Noteikti izmantojiet kontekstam labāko vārdu. Izvairieties no tādu vietniekvārdu kā „it” un „this” pārmērīgas izmantošanas, jo lasītājam var būt grūti noteikt, uz kādiem lietvārdiem viņi atsaucas.

Izvairieties arī no slenga un vulgāras valodas - atcerieties, ka rakstāt plašākai auditorijai, kuras attieksme un kultūras tieksme varētu atšķirties no jums.

Izvairieties no pārmērīga žargona

Ja esat savas jomas eksperts, jums var būt viegli lietot pazīstamu žargonu, neapzinoties, ka tas var mulsināt citus lasītājus.

Jums vajadzētu arī izvairīties no akronīmu lietošanas, kurus iepriekš neesat paskaidrojis.

Lūk, piemērs :

Mazāk skaidrs: PWA patiešām tiek uzskatīti par daudzplatformu attīstības nākotni. To pieejamība gan Android, gan iOS padara tos par nākotnes lietotni.

Uzlabots: progresīvās tīmekļa lietojumprogrammas (PWA) patiešām ir daudzplatformu attīstības nākotne. To pieejamība gan Android, gan iOS padara PWA par nākotnes lietotni.

Izmantojiet vienkāršo valodu

Izmantojiet mazāk vārdu un rakstiet tā, lai jebkurš lasītājs varētu saprast tekstu. ‌‌ Izvairieties no lieliem un gariem vārdiem. Vienmēr mēģiniet skaidrot jēdzienus un terminus pēc iespējas skaidrāk.

Vizuālā formatēšana

Teksta sienu ir grūti nolasīt. Pat skaidrākos norādījumus var pazaudēt dokumentā, kura vizuālais attēlojums ir slikts.

Viņi saka, ka attēls ir tūkstoš vārdu vērts. Tas ir patiesi rakstiski.

Bet ne jebkurš attēls ir tehniska dokumenta cienīgs. Tehnisko informāciju var būt grūti nodot tikai tekstā. Labi ievietots attēls vai diagramma var precizēt jūsu skaidrojumu.

Cilvēki arī mīl vizuālo materiālu, tāpēc tas palīdz tos ievietot pareizajās vietās. Apsveriet zemāk redzamos attēlus:

Pirmkārt, šeit ir emuāra fragments bez vizuālajiem materiāliem:

Šis ir tā paša emuāra fragments, bet ar attēliem:

Attēlu pievienošana rakstiem padara saturu ērtāku un saprotamāku. Papildus attēliem vajadzības gadījumā varat izmantot arī gifus, emocijzīmes, iegultus (sociālos medijus, kodu) un koda fragmentus.

Pārdomāts formatējums, veidnes un attēli vai diagrammas arī padarīs jūsu tekstu noderīgāku lasītājiem. Jūs varat pārbaudīt tālāk norādītās atsauces, lai iegūtu tehniskās rakstīšanas veidni no @Bolajiayodeji.

Veiciet rūpīgu pārskatīšanu

Labam jebkura veida rakstam nedrīkst būt pareizrakstības un gramatikas kļūdu. Šīs kļūdas var šķist acīmredzamas, taču tās ne vienmēr ir viegli pamanīt (it īpaši garos dokumentos).

Pirms nospiežat “publicēt”, vienmēr pārbaudiet pareizrakstību (jūs zināt, atzīmējiet savu Es un sakrustojiet savu Ts).

Ir vairāki bezmaksas rīki, piemēram, Grammarly un Hemingway lietotne, kurus varat izmantot, lai pārbaudītu gramatikas un pareizrakstības kļūdas. Jūs varat arī kopīgot sava raksta melnrakstu ar kādu, kuru pirms publicēšanas ir jāpārlasa.

Kur publicēt savus rakstus

Tagad, kad esat nolēmis sākt rakstīt tehniski, šeit ir dažas labas platformas, kurās varat sākt bez maksas ievietot tehnisko saturu. Tie var arī palīdzēt jums izveidot pievilcīgu portfeli nākamajiem darba devējiem, lai tos pārbaudītu.

Dev.to ir tūkstošiem tehnisku cilvēku kopiena, kurā gan rakstnieki, gan lasītāji var jēgpilni iesaistīties un dalīties idejās un resursos.

Hashnode ir mana emuāru veidošanas platforma ar lieliskām priekšrocībām, piemēram, pielāgotu domēnu kartēšanu un interaktīvu kopienu. Arī emuāra izveidošana šajā platformā ir vienkārša un ātra.

freeCodeCamp ir ļoti plaša sabiedrības un auditorijas sasniedzamība, un tā ir lieliska vieta savu rakstu publicēšanai. Tomēr jums būs jāpiesakās, lai rakstītu viņu publikācijai ar dažiem iepriekšējiem rakstīšanas paraugiem.

Jūsu pieteikumu var pieņemt vai noraidīt, taču neuztraucieties. Jūs vienmēr varat atkārtoti pieteikties vēlāk, kad jums kļūst labāk, un kas zina? Jūs varētu saņemt pieņemts.

Ja jūs rakstāt viņiem, viņi pirms publicēšanas pārskatīs un rediģēs jūsu rakstus, lai pārliecinātos, ka publicējat pēc iespējas pulētāku rakstu. Viņi arī kopīgos jūsu rakstus savās sociālo mediju platformās, lai palīdzētu vairāk cilvēkiem tos izlasīt.

Hackernoon ir vairāk nekā 7000 rakstnieku, un tā varētu būt lieliska platforma, lai jūs varētu sākt publicēt savus rakstus vairāk nekā 200 000 ikdienas lasītāju kopienā.

Hacker Noon atbalsta rakstniekus, pirms viņu publicēšanas platformā koriģē viņu rakstus, palīdzot izvairīties no izplatītākajām kļūdām.

Tehniskās rakstīšanas kursi

Tāpat kā visās citās jomās, arī tehniskajā rakstīšanā ir dažādi procesi, noteikumi, paraugprakse utt.

Tehniskās rakstīšanas kursu apmeklēšana palīdzēs jums apgūt visas lietas, kas jums jāapgūst, kā arī var ievērojami palielināt uzticību, lai sāktu rakstīt.

Šeit ir daži tehniskās rakstīšanas kursi, kurus varat pārbaudīt:

  • Google tehniskās rakstīšanas kurss (bezmaksas)
  • Udemy tehniskās rakstīšanas kurss (apmaksāts)
  • Hashnode tehniskā rakstīšana Bootcamp (bezmaksas)

Tehniskās rakstīšanas forumi un kopienas

Mēs vieni paši varam izdarīt tik maz, kopā, mēs varam paveikt tik daudz ~ Helēna Kellere

Izdevīgi ir būt kopienas vai foruma dalībniekiem kopā ar cilvēkiem, kuriem ir tāda pati aizraušanās kā jums. Jūs varat saņemt atsauksmes, labojumus, padomus un pat uzzināt dažus stila padomus no citiem sabiedrības rakstniekiem.

Šeit ir dažas kopienas un forumi, lai jūs varētu pievienoties:

  • Hašnode
  • Dev.to
  • Tehniskās rakstīšanas pasaule
  • Tehnisko rakstnieku forums
  • Uzrakstiet dokumentu forumu

Daži apbrīnojami tehniskie rakstnieki, kuriem sekot

Savā tehniskās rakstīšanas ceļā esmu ieradies un sekojis dažiem izciliem tehnikas rakstniekiem, kuru rakstīšanas ceļš, konsekvence un stils mani iedvesmo.

Tie ir rakstnieki, kurus es uzmeklēju un uzskatu par virtuālajiem padomdevējiem tehniskajā rakstīšanā. Dažreiz viņi atmet tehniskus rakstīšanas padomus, kas man šķiet noderīgi un no kuriem esmu daudz mācījies.

Šeit ir daži no šiem rakstniekiem (hipersaiti ar viņu twitter rokturiem):

  • Kvinsija Larsone
  • Edidiongs Asikpo
  • Katalīna bedre
  • Viktorija Lo
  • Boladži Ajodeji
  • Amruta Ranade
  • Kriss Bongers
  • Kolbijs Fajoks

Noslēguma vārdi

Lai sāktu ievietot tehnisko saturu, jums nav nepieciešams tehniskā raksta grāds. Varat sākt rakstīt savā personīgajā emuārā un publiskajās GitHub krātuvēs, vienlaikus veidojot savu portfeli un iegūstot praktisku pieredzi.

Tiešām - vienkārši sāciet rakstīt.

Prakse, izveidojot jaunus dokumentus esošajām programmām vai projektiem. GitHub vietnē ir vairāki atvērta pirmkoda projekti, kurus varat pārbaudīt un pievienot to dokumentācijai.

Vai ir kāda lietotne, kuru jums patīk izmantot, taču tās dokumentācija ir slikti uzrakstīta? Uzrakstiet savu un kopīgojiet to tiešsaistē, lai saņemtu atsauksmes. Varat arī ātri izveidot savu emuāru vietnē hashnode un sākt rakstīt.

Jūs iemācāties rakstīt, rakstot, lasot un domājot par to, kā rakstnieki ir izveidojuši savus varoņus un izdomājuši savus stāstus. Ja jūs neesat lasītājs, pat nedomājiet par rakstnieku. - Žans M. Auels

Tehniskie rakstnieki vienmēr mācās . Nirt jaunās mācību jomās un saņemt ārēju atgriezenisko saiti, labs rakstnieks nekad nebeidz slīpēt savu amatu.

Protams, labi rakstnieki ir arī rijīgi lasītāji. Pārskatot ļoti lasītus vai ļoti lietotus dokumentus, jūsu pašu rakstīšana noteikti uzlabosies.

Nevaru vien sagaidīt, kad redzēsi savus tehniskos rakstus!

Atsauces

Ievads tehniskajā rakstīšanā‌‌

Kā strukturēt tehnisko rakstu‌‌

Izpratne par auditoriju, kāpēc un kā

‌‌Tehniskās rakstīšanas veidne

Es ceru, ka tas bija noderīgi. Ja tā, sekojiet man Twitter un paziņojiet man!