Joel on Software

Joel on Software   Joel, szoftverekről

 

További "Joel on Software" cikkek magyar nyelven

További "Joel on Software" cikkek angol nyelven

E-mail a szerzőnek (angol nyelven)

 

Fájdalommentes funkcionális specifikáció - 4. rész: Tippek


Szerző: Joel Spolsky
Fordította: Plesz Gábor
2000. oktober 15.

Rendben van, beszéltünk arról, hogy miért van szükséged a specifikációra, mi is van benne, és kinek kell írnia. A sorozatnak ebben a negyedik és utolsó részében megosztok néhányat a tanácsaimból a jó specifikáció írással kapcsolatban.

A leggyakoribb panasz, amit azoktol a csapatoktól hallok, akik írnak specifikációt, hogy „senki sem olvassa el.” Ha senki sem olvassa el, akkor azok, akik írták, némiképpen hajlanak a cinizmusra. Ez olyan, mint a régi Dilbert karikatúra, ahol a mérnökök 4 hüvelyk vastak specifikációkat használnak az uszoda öltözőjének a bővítéséhez. A te tipikus nagy, bürokratikus cégednél mindenki hónapokat és hónapokat tölt unalmas specifikációk írásával. Ha egy elkészül, akkor felmegy a polcra, és soha többet nem jön onnan le többet, és a termék valami kacatból készül, tekintet nélkül arra, hogy mit mond a specifikáció, mivel senki nem olvassa a specifikációt, mert az olyan béna agyzsibbasztó. Maga a specifikáció írásának folyamata lehet, hogy egy jó edzés, mert mindenkit arra ösztönöz, minimum, hogy a problémákat végiggondolja. De az tény, hogy a polcra kerülő (olvasatlan és utált) specifikáció ha elkészül, olyan érzést kelt az emberben, hogy egy csomó munkát a semmiért kellet elvégezni.

Tehát, ha a specifikációdat soha sem olvassák el, akkor néhány szurkálódást azért fogsz kapni, amikor a termék szállítása megtörténik. Valaki (főnök, marketinges, vevő) azt mondja: „egy pillanat. Azt ígérted, hogy teszünk bele egy Mászó Gőzhajót! Hol van a mászó gőzhajóm?” És a programozó azt mondja: „nem, valójában, ha megnézed a 3. fejezet 4. alfejezetének 2.3.0.1. bekezdését, akkor a következő teljesen egyértelmű mondatot látod: ’nem kell mászó gőzhajó.’” De ezzel nem lesz elégedett a vevő, akinek mindig igaza van, így aztán a mérges programozó nekiállhat visszagyömöszölni a mászó gőzhajót a dologba, (sokkal inkább cinikussá válva a specifikáció irányába). Vagy a főnök mondja, „hé, minden megfogalmazás ezeken a dialógusablakokon túlságosan szószátyár, különben is minden dialógusablak tetejére kell még egy reklám.” És a programozó enyhén frusztrálva mondja „de hát te engedélyezted a specifikáció alapján a kódolást, és ott minden dialógusablak kinézete és tartama pontosan fel van sorolva!” Természetesen a főnök valójában nem olvasta, mivel amikor megpróbálta, az agya elkezdett elszivárogni a szemgödrein keresztül, és különben is ütközött a keddi golfmeccsével.

Vagyis. A specifikáció nagyon jó dolog, de akkor nem, ha senki sem olvassa. Specifikáció íróként ki kell cselesen rá kell venni az embereket, hogy olvassák el amit írtál, és meg kell próbálnod, hogy az erőfeszítésük miatt nehogy az egyébként sem túl sok agyuk kifollyék a szemgödreiken át.

Kicselezni az embereket az olvasásra valójában csak a jó írás dolga. De nem fair tőlem azt mondani, hogy „légy jó író”, aztán magra hagyni téged. Itt következik négy eszerű szabály, amit feltétlenül követned kell ahhoz, hogy olvasható specifikációt írj.

 

1. szabály: légy vicces

 

Hoppá, az első számú szabály az emberek cseles rábeszélésében a specifikációd olvasásához az az, hogy tedd élvezetes élménnyé. Ne mond azt nekem, hogy nem születtél vicces embernek, úgysem veszem be. Mindenkinek mindig vannak tréfás ötletei, csak az öncenzúrázza őket, mivel azt gondolja róluk, hogy "amatőr." Ugyan már. Néha meg kell szegni a szabályokat.



Ha elolvasod ezt a nagymennyiségű szemetet, amit ezen a weboldalon írtam, biztosan megfigyelted, hogy néhány hülyeséget mindenhova elszórtam. Négy bekezdéssel ezelőtt egy durva folyós-test tréfát eresztettem el, és kifiguráztam a főnököket, amiért golfoznak. Ennek ellenére nem gondolom azt igazából, hogy vicces vagyok. Én csak folyamatosan próbálkozom, és ha a vicceléssel próbálkozó kapálózásaim önmagukban is szórakoztatóak, már megérte. Ha specifikációt írsz, a legkönnyebben a példáknál tudsz valami vicceset írni. Minden esetben, ha arról kell beszélned, hogy egy tulajdonság hogyan működik, ne ezt mondd:

A felhasználó Ctrl+N-t nyom az új tábla létrehozásához és elkezdi az alkalmazottak felvitelét.

Írj valami ilyesmit:

Miss Röfi piszkálja a billentyűzetet a szemkihúzójával, mivel a kis pufók ujjai túl vastagok, hogy külön billentyűket tudjon megnyomni, Leüti a Ctrl+N-t, hogy létrehozza az új Udvarlók táblázatát és az első sorba beírja: "Jancsi".

Ha Dave Barry-t olvasol, akkor felfedezed, hogy az egyik legegyszerűbb módszer a tréfálkozáshoz ha senkit sem nevezel a nevén. „hiányos virslik” tréfásabb kifejezés, mint a „kutyák”. „Miss Röfi” tréfásabb, mint „a felhasználó”. A „különös érdeklődésű” helyett használj inkább „balkezes avokádó-földműves”-t. Ahelyett, hogy azt mondanád „az emberek, akik elutasítják a kötelező takarítást miután a kutyájuk büntetett”, mondd azt, hogy ezeket „olyan magányos rabhoz kell küldeni, aki még a póknak is fizetne a szexért.”

Ó, és igen, ha azt gondolog, hogy a viccelődés amatőr dolog, akkor sajnálom, de neked egyszerűen csak nincs humorérzéked. (Ne tagadd le. Az emberek, akiknek nincs humoroérzékük, mindig letagadják. Nem tudsz bolonddá tenni.) És ha olyan helyen dolgozol, ahol az emberek kevésbé becsülnek, mivel a specifikációid frissek, tréfásak és kellemes olvasni őket, akkor menj másik céghez dolgozni, mivel az élet olyan átkozottul rövid, hogy nem érdemes a napfényes óráidat zord és boldogtalan helyen töltened.

2. szabály: Specifikációt írni olyan, mint az agy számára végrehajtandó kódot írni.

Itt jön az, amiért azt gondolom, hogy a programozóknak a jó specifikáció írásával problémáik vannak.

Ha kódot írsz, akkor az elsődleges közönséged a fordító. Yeah, tudom, hogy az emberek is el tudják olvasni a kódot, de ez nekik rettenetesen nehéz dolog. A legtöbb programozó számára pont elég a kódot olyan állapotba hozni, amit a fordító fel tud dolgozni, és pontosan tud értelmezni; arra figyelni, hogy könnyen olvasható legyen emberek számára is az egy luxus. Ha ezt írod:

void print_count( FILE* a, char * b, int c ){ fprintf(a, "there are %d %s\n", c, b);} main(){ int n; n = 10; print_count(stdout, "employees", n) /* kód szándékosan elbonyolítva */ }

vagy

printf("there are 10 employees\n");

ugyanazt az eredményt kapod. Ez az amiért, azt gondolom, hogy a programozók hajlanak arra, hogy ilyesmiket írjanak:

Legyen a Címe(X) fügvény úgy definiálva, hogy az X felhasználó az RFC-822 szabványban meghatározott elektronikus-levélcímét adja vissza ANSI szövegként. Legyen A és B felhasználó, ahol A egy elektronikus levelet akar B-nek küldeni. Ezért A tetszöleges (de nem bármilyen) máshol definiált technikával létrehoz egy új üzenetet, és beírja a Címe(B) értéket a Címzett: szerkesztőmezőbe.

Pedig ezt így kellene specifikálni:

Miss Röfi ebédelni szeretne menni, így kezd egy új email-t, és beírja Jancsi címét a "Címzett:" dobozba.
Technikai megjegyzés: a cím szabványos Internet cím (megfelel az RFC-822 szabványnak)

Mindkettő ugyanazt "jelenti", elméletileg, kivéve, hogy az első példát lehetetlen anélkül megérteni, hogy az ember gondosan dekódolja, míg a második példa megértése egyszerű. A programozók gyakran megpóbálják a specifikációikat akadémiai székfoglaló bonyolultságúra megírni. Azt gondolják, hogy a "hibátlan" specifikációhoz az a fontos, hogy "technikailag" hibátlan legyen, és azzal kész.

A tévedés az az, hogy a hibátlanságon kívül még megérthetőnek is kell lennie, vagyis, programozói szóhasználattal úgy kell írni, hogy az emberi agy "le tudja fordítani". A számítógép és az emberi agy között az egyik nagy különbség, hogy a számítógép türelemmel meg fogja várni a fogalmak definiálását, amit később akarsz használni. De az emberek motiváció nélkül nem akarják megérteni, hogy miről beszélsz. Az emberek nem akarnak valamit dekódolni, hanem egyszerűen csak el akarják olvasni, és megérteni. Az emberek számára először egy vázlatot kell rajzolni, és aztán a részleteket kitölteni. A számítógépes programoknál elkezdi az ember az elejéről, és dolgozik a maga útján a végéig, folyamatosan teljes részletességgel. A számítógépet nem érdekli, hogy egy változó neve mennyire érthető elnevezés. Az emberi agy sokkal jobban érti a dolgokat, ha először egy élénk képet rajzolsz az elméjébe egy történet elmesélésével, akkor is, ha ez csak a töredéke a történetnek, mivel az elménk történetek megértésére fejlődött.

Ha a sakktáblát nézzük egy igazi játszma közepén, a tapasztalt sakkjátékosok akár egy vagy két másodperc alatt meg tudják jegyezni az állás minden részletét. De ha darabokból néhányat szabálytalan módon átmozgatunk(például néhány gyalogot az első sorba teszünk, vagy mindkét fekete futót fekete mezőre állítunk) sokkal, de sokkal nehezebb lesz nekik a táblát memorizálniuk. Ez más, mint ahogy a számítógép gondolkodik. A számítógép a lehetséges és a lehetetlen állásokat is egyfoma könnyen megjegyzi. Az emberi agy nem véletlen hozzáféréssel dolgozik; gyalogösvények mélyítik el a kapcsolatokat, és néhány dolgot sokkal könnyebb megérteni, mint másokat, mivel ezek sokkal mindennaposabbak.

Ezért, ha specifikációt írsz, próbáld meg elképzelni a személyt, aki majd olvasni fogja, és próbáld meg elképzelni, hogy mit fog mindenlépésnél ahhoz kérdezni, hogy megértse. Mondatról mondatra, kérdezd meg magadtól, ha ez az ember elolvassa ezt a mondatot, vajon megérti-e teljesen, abban az összefüggésben, ahogy elmondtad neki. Ha a célszemélyek közül valaki nem tudja, hogy mi az az RFC-822 vagy definiálnod kell, vagy, sokkal inkább, elásni az RFC-822 említését is egy technikai megjegyzésbe, így a menedzser-típusok, akik olvassák a specifikációt, nem fogják eldobni és befejezni az olvasást az első pillanatban, ahogy egy szakzsargon kifejezést meglátnak.

3. szabály: Írj olyan egyszerűen, amennyire csak lehetséges

Ne használj dagályos és formális nyelvet, mert azt gondolod, hogy szakszerűtlen egyszerű mondatokat írni. Használj olyan egyszerű nyelvet, amilyet csak tudsz.

Az emberek csak azért használják a "csinál" helyett a "használ" szót, mert azt gondolják a "csinál" szakszerűtlen. (Megint ez a szó: szakszerűtlen. Mindig, amikor valaki ezt mondja neked biztos lehetsz benne, hogy a valódi érvei elfogytak.) Tulajdonképpen sok ember gondolja úgy, hogy egyszerűen és tisztán írni és fogalmazni az valami rossz dolog.

Vágd szét a dolgokat rövid mondatokra. Ha problémát okoz egyszerűen leírni egy mondatot, vágd szét két vagy három felé.

 

      

 

"A magazinok kiragadnak egy idézetet a cikkből és óriási betűvel a lap közepére nyomtatják csak azért, nehogy egy teljes oldalon csak szöveg legyen."


 

 

Szüntesd meg a szövegek falát: az egész oldal csak szöveg. Az emberek megrémülnek és nem olvassák el. Mikor láttál utoljára egy népszerű magazinban egy teljes oldal szöveget? A magazinok kiragadnak egy idézetet a cikkből és óriási betűvel a lap közepére nyomtatják csak azért, nehogy egy teljes oldalon csak szöveg legyen. Használj számozott vagy pöttyökkel jelzett listákat, képeket, grafikonokat, táblákat és egy kevés üres helyet, mert így az olvasás könnyebbnek "tűnik".

Semmi sem erősíti a specifikációt annál jobban, mint rengeteg és még több képernyőkép. Akárki, aki Windows-hoz ír specifikációt invesztáljon be egy másolat Visual Basic-be, és tanulja meg legalább annyira, hogy képernyő-modelleket tudjon készíteni. (Mac-hez használj REAL Basic-et; Web oldalakhoz Front Page-et vagy Dreamweaver-t. Ezután fényképezd le a képernyőket (Ctrl+PrtSc) és illeszd be őket a specifikációdba.

4. szabály: A végén olvasd újra és nézd át néhányszor

Ja igen, szóval eredetileg ide egy hosszú és fontos szabályt terveztem, de ez a szabály sajnos túl egyszerű és nyílvánvaló. Olvasd át és nézd át a specifikációt néhányszor, rendben? Ha találsz olyan mondatot, ami nem szuper fantasztikus módon egyszerűen megérthető, írd át.

Olyan sok időt takarítottam meg azzal, hogy a 4. szabályt nem ragoztam túl, hogy még egy szabályt kell mondanom.

5. szabály: A sablonok kártékonyak

Kerüld el, hogy szabványos sablont készíts a specifikációkhoz. Talán először azt gondolod, hogy az a fontos, hogy "minden specifikáció ugyanúgy nézzen ki." De nem. Miben segít a különbözőség? A saját könyvespolcodon ugyanúgy néz ki minden könyv? És szeretnéd, hogy így legyen?

Ellenkezőleg, ha sablonjaid vannak, akkor egy csomó kötelező fejezetet adsz hozzá a sablonodhoz, amiről azt gondolod, hogy fontos mindenhez. Például: Nagy Bill úgy döntött, hogy mostantól kezdve minden Microquish terméknek tartalmaznia kell Internet összetevőt. Így aztán most a sablonnak van egy fejezete, aminek a neve "Internet Összetevő." Akármikor akárki specifikációt ír, nem számít milyen egyszerűt, meg kell töltenie egy fejezetet aminek a címe "Internet Összetevő", akkor is, ha éppen a Microquish Billentyűzet specifikációját készíti. (És csodálkoztál, hogy miért szaporodik gombaként az Internet vásárlás gomb a billentyűzeteken).

Hogy összefoglaljam a fejezetet, a sablon kicsit hosszú lett. (Itt egy példa a nagyon, nagyon rossz specifikáció sablonra. Kinek kell bibliográfia a specifikációba, mi az ördögnek? Vagy szójegyzék?) A probléma az ilyen hosszú sablonnal, hogy elriasztja az embereket a specifikáció írástól, mert fölösleges munkának néz ki.

A specifikáció egy olyan iromány, amit az emberek el akarnak olvasni. Ebből a szempontból nem különbözik egy New York Times cikktől, vagy egy irodalom fogalmazástól. Hallotál már olyanról, hogy a tanár sablont ad a fogalmazáshoz? Olvastál már jó fogalmazást, ami illett volna egy sablonba? Egyszerűen felejtsd el.



A fordítás alapjául szolgáló angol cikk címe: Painless Functional Specifications Part 4  

Joel Spolsky a Fog Creek Software alapítója. A Fog Creek egy apró szoftvercég, székhelye New York City. Joel a Yale egyetemen végzett, majd programozóként és menedzserként dolgozott a Microsoftnál, a Viacomnál és a Junonál.


Az itt olvasható oldalak egyetlen személy véleményét tükrözik.
Minden itt megjelenő tartalom ©1999-2005 Joel Spolsky. Minden jog fenntartva.

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky