Izstrādātāji Kāpēc jums nevajadzētu izlaist dokumentāciju

Mobilo lietotņu, tīmekļa lietotņu, darbvirsmas lietotņu vai JavaScript bibliotēku attīstības jomā dokumentācijai ir svarīga loma, kas varētu noteikt programmatūras izstrādes panākumus. Bet, ja jūs kādreiz esat pabeidzis dokumentāciju, jūs piekrītat man, ka tas ir diezgan mazākais mīļākie, ko darīt izstrādātājiem.

Atšķirībā no rakstīšanas koda (kas ir tas, ko izstrādātāji ir pierakstījušies), dokumentācijai (ko mums nebija) ir jābūt viegli saprotamam visi. Tehniski mums ir jātulko mašīnas valoda (kods) cilvēkam saprotamā valodā, kas ir stingrāka par to, kas izklausās.

Lai gan dokumentācija var būt reāls apgrūtinājums, dokumentācija ir svarīga, un tā sniegs priekšrocības jūsu lietotājiem, saviem kolēģiem un īpaši sev.

Laba dokumentācija palīdz lietotājiem

Dokumentācija palīdz lasītājam saprast, kā darbojas kods, acīmredzami. Bet daudzi izstrādātāji kļūdās, pieņemot, ka programmatūras lietotāji būs prasmīgi. Līdz ar to dokumentācija var būt tievs materiāls, izlaižot daudzus būtiskākos elementus, kas tam bija jābūt no sākuma. Ja jūs esat savvy šajā valodā, jūs varat izdomāt lietas pēc savas iniciatīvas; ja neesat, tad esat pazudis.

Lietotājiem paredzētā dokumentācija parasti sastāv no praktiskas izmantošanas vai “kā”. Parasti īkšķis, veidojot dokumentāciju vispārējiem lietotājiem tai jābūt skaidrai. Cilvēkiem draudzīgu vārdu lietošana ir labāka nekā tehniskie termini vai žargons. Ļoti pateicīgi būs arī reālās izmantošanas piemēri.

Labs izkārtojuma dizains arī palīdzētu lietotājiem skenēt caur katru dokumentācijas sadaļu bez acu sprieduma. Daži labi piemēri (pazīstami kā mani favorīti) ir Bootstrap un WordPress dokumentācija. “Pirmie soļi ar WordPress”.

Tas palīdz citiem izstrādātājiem pārāk

Katram attīstītājam būs savs kodēšanas stils. Bet, kad runa ir par darbu komandā, mums bieži būs jāapmainās ar citiem komandas biedriem. Tāpēc tas ir būtiski vienoties par standartu saglabāt visus tajā pašā lapā. Pareiza rakstiska dokumentācija būtu atsauce uz komandas vajadzībām

Bet atšķirībā no gala lietotāja dokumentācijas, šī dokumentācija parasti apraksta tehniskās procedūras piemēram, kodu nosaukuma konvencija, kas parāda, kā jāveido konkrētas lapas un kā API darbojas kopā ar koda piemēriem. Bieži vien mums arī būtu jāraksta dokumentācija ar kodu (pazīstams kā komentārus), lai aprakstītu kodu.

Turklāt, ja jums ir jauni dalībnieki jūsu komanda vēlāk, šī dokumentācija varētu būt efektīvs veids, kā tos apmācīt, tāpēc jums nav jādod viņiem 1-uz-1 uz leju uz kodu.

Savādi tas palīdz arī kodētājam

Smieklīgi par kodēšanu ir dažreiz pat paši attīstītāji paši nesaprot, ko tie ir rakstījuši. Tas jo īpaši attiecas uz gadījumiem, kad kodi ir atstāti neskarti mēnešiem vai pat gadiem.

Pēkšņa nepieciešamība pārskatīt kodus vienu vai otru iemeslu dēļ atstātu vienu brīnumu par to, kas notiek viņu prātos, kad viņi rakstīja šos kodus. Vai nav pārsteigts: es biju šajā situācijā. Tas ir precīzi kad es vēlējās Es pareizi dokumentēju savu kodu.

Dokumentējot kodus, varat ātri un bez vilšanās nokļūt jūsu kodu apakšā, ietaupot daudz laika, ko var iztērēt, lai iegūtu izmaiņas.

Kas padara labu dokumentāciju?

Labi dokumentācijas veidošanai ir vairāki faktori.

1. Nekad Uzņemieties

Neuzskatiet, ka jūsu lietotāji zina, ko jums zināt, kā arī viņi gribu zināt. Tas vienmēr ir labāk sākt no paša sākuma neatkarīgi no lietotāju prasmes līmeņa.

Ja, piemēram, izveidojāt jQuery spraudni, jūs varat iedvesmot no SlickJS dokumentācijas. Tas parāda, kā strukturēt HTML, kur ievietot CSS un JavaScript, kā inicializēt jQuery spraudni tā pamata līmenī, un pat parāda visu galīgo atzīmi pēc visu šo materiālu pievienošanas, kas ir kaut kas acīmredzams.

Apakšējā līnija ir dokumentācija, kas rakstīta ar lietotāja domāšanas procesu, nevis izstrādātāju. Tādā veidā tuvojoties savai dokumentācijai, jūs iegūsiet labāku perspektīvu savu darbu organizēšanā.

2. Izpildiet standartu

Pievienojot dokumentāciju, kas saskan ar kodu, izmantot valodu gaidīto standartu. Vienmēr ir laba ideja aprakstīt katru funkciju, mainīgos lielumus, kā arī vērtību, ko atdod funkcija. Šeit ir labas inline dokumentācijas piemērs PHP.

 / ** * Pievieno pielāgotas klases ķermeņa klasēm. * * @param masīvs $ klases Ķermeņa elementu klases. * @return masīvs * / funkcija body_classes ($ class) // Pievieno grupas blogu blogiem ar vairāk nekā 1 publicēto autoru. ja (is_multi_author ()) $ class [] = 'grupas emuārs';  atgriezt $ klases;  add_filter ('body_class', 'body_classes'); 

Tālāk norādītas dažas atsauces par inline dokumentācijas formatēšanu ar labāko praksi PHP, JavaScript un CSS:

• PHP: PHP dokumentācijas standarts WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Ja lietojat SublimeText, es ieteiktu instalēt DocBlockr, kas gudri iepriekš ievietos jūsu kodu ar inline dokumentāciju.

3. Grafiskie elementi

Izmantojiet grafiskos elementus, viņi runā labāk nekā teksts. Šie plašsaziņas līdzekļi ir noderīgi, jo īpaši, ja veidojat programmatūru ar grafisko interfeisu. Varat pievienot norādes elementus, piemēram, bultiņas, apli, vai nekas, kas var palīdzēt lietotājiem noskaidrot, kur doties, lai veiktu soļus, bez minējumiem.

Tālāk sniegts piemērs no torņa lietotnes, kur jūs varat izdarīt iedvesmu. Viņi efektīvi izskaidro, kā versiju kontrole darbojas patīkami, kas padara to saprotamāku nekā vienkāršas teksta komandas.

4. Sadalīšana

Jūs varat apsvērt dažas lietas dokumentācijā aizzīmogotos sarakstos un tabulās, jo tas atvieglo satura skenēšanu un lasīšanu lietotājiem.

Pievienojiet satura tabulu un sadaliet dokumentāciju viegli sagremojamās sadaļās, tomēr saglabājiet katrai sadaļai atbilstošu informāciju par nākamo. Saglabājiet to īsu un vienkāršu. Zemāk ir labi organizētas dokumentācijas piemērs Facebook. Satura tabulā atrodams, kur mēs vēlamies pāriet uz klikšķi.

5. Pārskatīt un atjaunināt

Visbeidzot, pārskatiet dokumentāciju par kļūdām un, ja nepieciešams, pārskatiet un, ja ir būtiskas izmaiņas produktā, programmatūrā vai bibliotēkā. Jūsu dokumentācija nebūtu noderīga ikvienam, ja to regulāri neatjaunina kopā ar jūsu produktu.