Девелопери Зашто не бисте требали прескочити документацију

У домену развоја мобилних апликација, веб апликација, десктоп апликација или ЈаваСцрипт библиотека, документација игра важну улогу која би могла да одреди успех развоја софтвера. Али ако сте икада направили документацију, сложили бисте се са мном да је то најмање омиљена ствар за програмере.

За разлику од писања кода (што су програмери потписали да ураде), документација (коју нисмо) мора и мора бити лако сварљива сви. Технички, морамо преводити машински језик (код) на језик који је разумљив људима, што је теже него што звучи.

Иако то може бити стварно оптерећење, писање документације је важно и пружиће предности вашим корисницима, вашим колегама, а посебно вама.

Добра документација помаже корисницима

Документација помаже читаоцу разумете како ради код, очигледно. Међутим, многи програмери праве грешку претпостављајући да ће корисници софтвера бити искусни. Дакле, документација може бити танак материјал, прескочивши много битних ствари које је требало да садржи од самог почетка. Ако сте паметни у језику, можете схватити ствари на своју иницијативу; ако нисте, онда сте изгубљени.

Документација намењена корисницима обично се састоји од практичне употребе или “како да”. То је правило при изради документације за опште кориснике требало би да буде јасно. Употреба речи прилагођене људима је боље од техничких термина или жаргона. Примјери стварне употребе ће такођер бити високо цијењени.

Добар дизајн дизајна би заиста помогао корисницима да скенирају кроз сваки део документације без напрезања очију. Неколико добрих примјера (познатији као моји фаворити) су документација за Боотстрап и ВордПресс “Први кораци са ВордПресс-ом”.

И то помаже другим програмерима

Сваки девелопер ће имати свој стил кодирања. Али, када је у питању рад у тиму, често ћемо морати да делимо шифре са другим колегама. Зато је то неопходно консензус о стандарду да задржите све на истој страници. Одговарајућа писана документација би била референца коју тим треба

Али за разлику од документације крајњег корисника, ова документација обично описује техничке процедуре као што је конвенција о именовању кодова, која показује како би одређене странице требале бити изграђене и како АПИ ради заједно са примјерима кода. Често бисмо такође морали да напишемо документацију у линији са кодом (познатим као цомментс) да опише шта ради код.

Поред тога, у случају где имате придруживање нових чланова касније, ова документација може бити временски ефикасан начин да их обучите, тако да не морате да им дате један на један.

Чудно је и да помаже кодеру

Смешна ствар кодирања је понекад чак и сами програмери не схватају код који су написали. Ово је посебно тачно у случајевима када су кодекси остављени нетакнути мјесецима или чак годинама.

Изненадна потреба за поновним разматрањем кодова из једног или другог разлога оставила би некога да се запита шта се дешава у њиховим мислима када су написали ове кодове. Не изненадите се: већ сам био у овој ситуацији. Ово је прецизно кад сам пожелела Ја сам исправно документовао свој код.

Документујете своје кодове, моћи ћете брзо и без фрустрација доћи до дна ваших кодова, штедећи вам пуно времена које можете потрошити на измјене у.

Шта чини добру документацију?

Постоји неколико фактора за изградњу добре документације.

1. Никада немојте претпостављати

Немојте претпостављати да ваши корисници знају шта ти знају као и шта они Хоћу да знам. Увек је боље почети од самог почетка без обзира на ниво стручности корисника.

Ако сте направили јКуери плугин, на пример, можете узети инспирацију из СлицкЈС документације. Показује како структурирати ХТМЛ, гдје ставити ЦСС и ЈаваСцрипт, како иницијализирати јКуери плугин на његовом најосновнијем нивоу, па чак и приказује комплетну коначну ознаку након додавања свих ових ствари, што је нешто очигледно..

Доња линија је документација написана са процесом размишљања корисника, а не програмера. Приближавање сопственој документацији на овај начин ће вам дати бољу перспективу у организовању вашег дела.

2. Следите Стандард

Додавањем документације која је у складу са кодом, користите стандард који се очекује од језика. Увијек је добра идеја описати сваку функцију, варијабле, као и вриједност коју враћа функција. Ево примера добре инлине документације за ПХП.

 / ** * Додаје прилагођене класе низу класа тела. * * @парам арраи $ цласс Класе за елемент тијела. * @ретурн арраи * / фунцтион боди_цлассес ($ цлассес) // Додаје класу групног блога блоговима са више од 1 објављеног аутора. иф (ис_мулти_аутхор ()) $ цласс [] = 'група-блог';  ретурн $ цлассес;  адд_филтер ('боди_цласс', 'боди_цлассес'); 

Следи неколико референци за форматирање инлине документације са најбољим праксама у ПХП-у, ЈаваСцрипт-у и ЦСС-у:

• ПХП: ПХП документација Стандард за ВордПресс
• ЈаваСцрипт: УсеЈСДоц
• ЦСС: ЦССДоц

Ако користите СублимеТект предлажем да инсталирате ДоцБлоцкр који ће паметно унапред попунити ваш код помоћу инлине документације.

3. Графички елементи

Користите графичке елементе, они говоре боље од текста. Ови медији су корисни, посебно ако правите софтвер са графичким интерфејсом. Можете додати елементе за показивање као што су стрелице, круг или све што може помоћи корисницима да схвате где да иду да би извршили кораке, без нагађања.

Следи пример из Товер апликације где можете црпити инспирацију. Ефикасно објашњавају како контрола верзија функционира на угодан начин што га чини разумљивијим од кориштења једноставних текстуалних командних линија.

4. Секција

Размислите о оматању неколико ствари у документацији у листама и табелама са ознакама, јер то олакшава скенирање и читање више садржаја за кориснике.

Додајте садржајну табелу и подијелите документацију у лако пробављивим дијеловима, али задржите сваки одјељак релевантан са сљедећим. Нека буде кратка и јасна. У наставку је примјер лијепо организиране документације на Фацебооку. Садржај нас води камо желимо да скочимо једним кликом.

5. Ревизија и ажурирање

На крају, прегледајте документацију због грешака и ревидирајте када је то потребно или када и када дође до значајних промена на производу, софтверу или библиотеци. Ваша документација никоме не би била од користи ако се не редовно ажурира уз ваш производ.