Разработчици Защо не трябва да прескочите документацията

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

За разлика от писането на код (това е, което разработчиците са направили), документацията (която не сме) трябва и трябва лесно да се усвоява от всеки. Технически, трябва да преведем машинен език (код) на език, разбираем за хората, който е по-труден, отколкото звучи.

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

Добрата документация помага на потребителите

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

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

Доброто оформление също би помогнало на потребителите да сканират всеки раздел на документацията, без да се натоварват с очите. Няколко добри примера (известни още като моите любими) са документация за Bootstrap и WordPress. “Първи стъпки с WordPress”.

Той също така помага на други разработчици

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

Но за разлика от документацията за крайния потребител, тази документация обикновено описва технически процедури като конвенция за именуване на кодове, показваща как трябва да се конструират определени страници и как API работи заедно с примерите за кода. Често би трябвало да напишем документацията с кода (известен като коментари), за да опише какво прави кода.

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

Странно също така помага на кодерите

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

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

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

Какво прави за добра документация?

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

1. Никога не приемайте

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

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

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

2. Следвайте стандарта

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

 / ** * Добавя потребителски класове към масива от класове на тялото. * * @param array $ class Класове за елемента body. * @return array * / function body_classes ($ classes) // Добавя клас от блог към блогове с повече от 1 публикуван автор. if (is_multi_author ()) $ class [] = 'групов блог';  return $ classes;  add_filter ('body_class', 'body_classes'); 

По-долу са дадени няколко справки за форматиране на вградена документация с най-добрите практики в PHP, JavaScript и CSS:

• PHP: Стандарт за документация на PHP за WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

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

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

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

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

4. Разрез

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

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

5. Преразглеждане и актуализиране

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