Így kezdtem el írni funkcionális és termékspecifikációkat — Wikispeci (1. rész)
avagy miért nem elégedtem meg az ismert és máshol bevált módszerekkel.
Ez az 1. része a háromrészes cikksorozatnak:
1. Így kezdtem el írni funkcionális specifikációkat
2. Így írj te is érthető funkcionális- és termékspecifikációkat
3. Ezekkel írj te is érhető funkcionális- és termékspecifikációkat
TARTALOMJEGYZÉK
- Előszó
- A kezdetek és az első pofon
- A paradigmaváltás, a wikispeci megszületése
- A bevált recept
- Eszközök amiket próbáltam
- Jelenkori kísérletezgetések
1. ELŐSZÓ
Régóta írok üzleti igényeket, amiben megismerhetők egy adott projekt alapvető kívánalmai, hogy a projektben résztvevőkkel egy húron pendüljünk már a megismerési szakaszában. Ez a dokumentum folyamatosan bővül és változik ahogy gyűlnek össze az elképzelések, ötletek és derülnek ki a részletek. Az ideális az, ha az egész projektcsapat részt vesz a szerkesztésében.
Ahogy fogalmazódnak meg a részleteket egy ponton túl a dokumentum túlnő “igény” jellegén és egy sokkal részletesebb leírás kerekedik belőle, amit pontosabban részletezi, specifikálja a termék működését.
Sokszor ezek a hosszú dokumentumok annyi információt tartalmaznak, hogy több logikai bukfenc is keletkezik, hiszen ha egy működési elv megváltozik, az kihatással van más részek működésre, funkcióira. Ez hatványozottan igaz, ha a megfogalmazott elemek, funkciók sokszor visszatérnek a doksiban. Ezt észben tartani nem egyszerű, főleg ha több ember szerkeszti vagy több különböző projekten is dolgunk.
Évek során jó pár specifikációt írtam: 20–30 között a megvalósult és további 10–15 a végül félbehagyott vagy nem megvalósult projektekre. A tartalomjegyzéket nem számolva vannak köztük rövidebb (5 oldal (A4)) és hosszabb (93 oldal) változatok is egyaránt. Minden egyes projektnél picit fejlesztettem speciírási metódusomon, míg megtaláltam a bevett struktúrát és az alkalmas eszközt.
Igen, léteznek különböző sztenderdek, mint pl. System Requirement Specification (SRS, rendszerigény specifikáció) is. A tapasztalataim alapján pár hardcore fejlesztőn kívül szinte senki sem szerette olvasni, mert túl száraz és nagyon sokszor nem megfelelően rendezett a struktúrája.
Éppen ezért készítettem egy három részes cikksorozatot a funkcionális specifikáció, avagy wikispeci írási módszeremről:
- az első rész (lejjebb) azt mutatja be, hogy mi alapján alakult ki a jelenleg is használt módszerem,
- a második rész mutatja be a gyakorlatban a metódust és a javasolt eszközöket az írásához, míg
- a harmadik rész az eszközöket mutatja be felületesen.
2. A KEZDETEK ÉS AZ ELSŐ POFON
2011-et írunk, két éve dolgoztam a digitális projektek világában, amikor találkoztam egy akkoriban számomra “komolyabb” brieffel egy készülő portálhoz.
Az emailben kapott Word doksi már üzleti igény szinten volt átgondolva és nem csak “szeretnék egy webportált” jellegű e-mail volt. Volt benne célcsoport meghatározás, sitemap, le volt írva, hogy milyen elemeket és tartalmakat szeretnének az egyes oldalakra, tehát akkori szemmel részletesnek tűnt. A csapatunknak UI-t kellett tervezni és azt lefejleszteni. Nekem lényegében csak a menedzsmenti feladatok jutottak: a látszat miatt szinte gondolkoznom sem kellett, hogy a koncepció és az összefüggések egyáltalán rendben vannak-e.
És itt futottam bele az első pofonba.
Történ ugyanis, hogy a megrendelő felületesen gondolta át a felületeket, tele következetlenséggel és hiányossággal. Hiába lett ez alapján szépen megtervezett a felhasználó felület, a lefejlesztett portál végeredményben nem volt felhasználóbarát és korántsem logikus. Ez rengeteg változtatást - így Change Requestet (CR) és Feature Requestet (FR) - vont maga után. Ez még nem is probléma egy agilis környezetben, de a büdzsé rugalmatlan, a munkaórák száma pörögnek felfelé és az alagút vége folyamatosan távolodik. A projekt végül nemhogy nullszalldós, de óriási bukta lett.
A probléma az volt, hogy a dokumentumban nem voltak pontosan meghatározva a funkciók, a visszatérő elemek (pl. egy felhasználói adat) a dokumentáció különböző részében más feltételekkel működtek, és hiányoztak a lehetséges esetek forgatókönyvei. Ezért ahány ember, annyiféleképpen értelmezte a leírtakat, már ha elolvasta a teljes anyagot.
A megrendelő többet, a fejlesztő kevesebbet, a design szépet, míg én - a PM - csak mihamarabbi boldog projektzárást vizionáltam, hiszen vár a többi projekt is.
Sajnos ennek az iparágnak az egyik nagy problémája, hogy amint a projekt véget ért, még karbantartási feladatok lehetnek a “kész” termékkel, de lényeges továbbfejlesztés, mely a felhasználásból adódó visszajelzéseket is hivatott megoldani, már nem. Mindenki örült, hogy kihoztuk a szükséges minimumot a projektből, de ez az MVP (Minimum Viable Product — magyarul talán: “Legszükségesebb funkciójú termék”) — nem az az MVP…
Az elkészült portált a felhasználók használták, de láthatóan a szükség és a tartalom miatt és nem azért mert szerették.
Az esetet követően vettem egy mély levegőt és az új tapasztalattal álltam neki a beérkező projekteknek.
A többi megrendelő továbbra is egy vagy két oldalas briefeket küldtek. Nem baj: mi vagyunk a szakemberek, hogy részleteket kidolgozzuk. Különben is, nemhogy a pontos dokumentáció, de a marketingesek világában az üzleti igény ritkaságszámba ment.
A kapott briefek alapján elkezdtem magam megírni az “üzleti”, pontosabban termék vagy sokkal inkább funkcionális igényeket: megterveztem a website felépítését, belevettem azokat a gondolatokat és működési terveket, amikről úgy gondoltam, hogy fontos lehet és emellett igyekeztem a lehető legpontosabban megfogalmazni ezek működését, kevés esélyt hagyva a félreérthetőségnek. Mint egy szerződés, amiben a cél az, hogy a másik fél mit ne gondoljon még bele a projektbe.
A késznek vélt dokumentumot kiküldtem a megrendelőknek, akik átolvasták és megjegyzéseket fűztek hozzá. A kapott válaszok alapján módosítottam a tartalmat és így ment ez addig, amíg közös nevezőre nem kerültünk. Ha lusták voltak elolvasni, akkor is volt egy dokumentum amire tudtunk hivatkozni, így elejét vettük az ingyenes CR-ekenek. Mi csak nyertünk vele, még ha sok idő is ment bele az elején a tervezési szakaszba.
Ha lezártuk a doksit, utána jöhetett a design. Sok esetben amíg a doksi készült a háttérben már zajlott a vizuális tervezés, hogy ne legyen csúszás a határidőkkel. Tudtuk, hogy ez a folyamat nem túl hatékony, hiszen később módosítanunk kell a terveken. Ha a design kész lett, ment a fejlesztés, aki a designt látva és a dokumentumot összeolvasva elsőre vállalható eredményt rakott össze és jóval kevesebb volt a CR. Csak a bugfixekre kellett koncentrálnunk. Ez teljesen “vízeséses projektvezetés”, az agilitás legminimálisabb jelenlétével.
Viszont nem számoltam akkoriban az utókövetéssel: ha később valami változott a rendszerben, azt nem vezettem át. Ez később egy újabb funkció fejlesztésével ismét azt eredményezte, hogy logikai anomáliák kerültek a rendszerbe és kezdődött a kapkodás. Szerencsére az ilyen eset ritka volt, mert jellemzően gyors kifutású promóciós, nyereményjátékos microsite-okat vagy kisebb eseményekhez kapcsolódó portálokat, egyszerűbb webshop jellegű oldalakat vagy kreatív technológiás megoldásokat (kütyüket) kellett tervezni és fejleszteni rendezvényekre. Ezek pedig hamar végetérnek és felesleges a későbbi fejlesztés, hacsak később elő nem húzzuk megint a kalapból egy másik kampány miatt.
Ahogy fejlődtem, úgy kaptam gógyisabb / digitálisan tapasztalt megrendelőket, akik okosan kommentelték a dokumentumokat. Ezért folyamatosan bővíteni kellett a működési leírást, egyre részletesebben megfogalmazva, egyre több mindenre gondolva.
És ahogy nőtt a doksi és jöttek a visszajelzések, annál több következetlenség is került a leírásba. Ezek általában az anyag újra elolvasását követően kibuktak már a tervezéskor, de így is irgalmatlan sok idő ment el szerkesztéssel.
A nehézség ebben a karrierszakaszomban az volt, hogy továbbra is hagyatkoztam a fejlesztő képzelőerejére és tapasztaltságára. Ez mindaddig nem is volt nehézség, amíg egy helyen ültünk és tudtunk egyeztetni, viszont amikor külső beszállítókat is bevontunk a projektben, megint kezdődött a 💩 lapátolás a határidő közeledtével.
Kis kitérő: 2012-ben járunk és ekkor ismerkedtem meg először a drótváz fogalmával. A terveket Balsamiqban és Powerpointban készítettem a designernek, hogy elkerüljük a felesleges “mire gondoltam” ping-pongokat.
Nagyon élveztem, hogy pár perc alatt meg tudtam neki mutatni hogy hogyan ne szálljon el a képzelete egy-egy funkciónál. Ezt megrendelők nem látták, ők csak a letervezett UI elemeket kommentelték.
Tudtam, hogy még jobban definiálni kell a dolgokat, még több idő megy el tervezésre, de meg is volt az eredménye az alapos tervezésnek, ha hagytak rá időt. Már ha hagytak…
3. A PARADIGMAVÁLTÁS, A “WIKISPECI” MEGSZÜLETÉSE
2013-ban munkahelyet váltottam. Ez egy más liga volt: több és profibb fejlesztési munkamódszer és kaptam egyből két komolyabb nemzetközi ügyfelet: az egyik megrendelő egy több éve futó 200 000 aktív felhasználót számláló egyedi CRM rendszeres továbbfejlesztését kérte, míg a másik megrendelő rendezvényeken használatos trendi és fiatalos megoldásokat várt (nevezzük kreatív technológiának). Mélyvíz. Marianna-árok. Volt három próbahónapom bizonyítani.
A kihívás nem is a kreatív technológia volt, hanem a CRM. Az elődöm olyan specifikációkat írt, hogy a könnyem kicsordult, amikor megnyitottam a word fájlokat: irgalmatlan mennyiségű szöveg és kikezdhetetlen leírás a funkciókra és felületekre megspékelve egy üzleti logika dokumentummal. Ez már közelebb volt az SRS dokumentumokhoz és ezzel mindahhoz a száraz dokumentációhoz, amit eddig kerültem.
A sokkot követő első dolgom az volt, hogy felússzak, vegyek egy nagy levegőt, majd visszamerüljek a mélyvízbe: újragondoltam, hogy mi tudok az eddig tanultakból hasznosítani és mi tudok kezdeni a jelenlegi információkkal.
Azt tudtam, hogy sokkal több energiát kell belefektetnem, mint eddig, de azt is tudtam, hogy nem tudok ennyi információt észben tartani, így trükkhöz kellett folyamodnom.
A doksiírást továbbra is azzal kezdtem, hogy átgondoltam az oldaltérképet, megfogalmaztam a rajtuk fellelhető lehetőségeket és jelöltem, hogy az adott felülethez ki férhet hozzá.
És itt jött a nagy változás: az előző munkahelyemet úgy hagytam ott, hogy adatkezelési, szerződéses és szabályzatokkal kapcsolatos dokumentumokat kellett összeállítsak és kiküldenem jogászoknak elfogadására. Ezekben a doksikban rengeteg dokumentumon belüli pontokra való hivatkozás volt: ha kiegészült a tartalom előfordult, hogy más oldalra (“lásd 8. oldal”) vagy pontra (“lásd 1.3. pont”) kellett hivatkozni.
Azt már akkor is tudtam, hogy a Wordben a kereszthivatkozások funkcióval remekül lehet dinamikusan hivatkozni más számozott pontokra. Ha változik a számozás, azt a hivatkozott szövegben a rendszer lekezeli. Ez a speciírásban is jól jött, mert így a visszatérő elemeket jelölhettem külön pontokban. Nem csak funkciókat, hanem elemeket vagy fogalmakat.
Pl. egy blog vagy portál tervezésekor a “cikk címe” vagy “lead szövege” több felületen is szerepel, de csak az egyik felület leírásában részletezem.
A többi felületet leíró fejezetben erre a pontra hivatkoztam vissza kereszthivatkozással. Utólag rájöttem, hogy ez egy rossz döntés, mert minél több a hivatkozható elem, annál jobban emlékeznem kell, hogy hol használtam először. Erre a megoldás, hogy mindent amire hivatkozni akarok, külön fejezetekben rendszerezek.
Ekkor a specifikáció már három részletből épült fel:
- Brief (kinek, miért és milyen koncepciót) és fejlesztési környezet (pl. szerver, OS…stb.)
- Oldaltérkép és oldalak bemutatása
- Szótár, ami a kifejtette egy adott elem tulajdonságát (pl. mi a “cikk címe”)
Tehát, ha valamit meg akarok jeleníteni egy felületen, akkor azt a szótárból kell kikeresnem: ha nincs a szótárban, akkor létrehozom külön pontként és készítek hozzá egy rövid leírást. De visszafele is működik: ha a szótárt kezdem el kitölteni és elakadok, akkor tudom folytatni a felülettel.
Ezt a megoldást hónapokig és több projektben használtam. Eszméletlenül dagadt a mellem, hogy viszonylag minimális emlékezőképességgel könnyen átláthatom a teljes rendszert és a hivatkozások miatt látom, hogy miből főzhetek. Az meg csak hab a tortán, hogy maga a tervezés kb. eteti magát.
Itt fontos megjegyeznem, hogy az akkori fejlesztő kollégákat is bevontam már a tervezési folyamatba, akik becsülettel átolvasták a duzzadó dokumentumokat és nagyon durván kikezdték ott ahol tudták, logikai buktatókat keresve, vagy csak fejlesztési nehézséget jelezve. Az külön öröm volt, ha javaslatot is kaptam egy-egy hatékonyabb megoldásra.
Nagyon eredményes volt, ráadásul a megrendelő is becsülettel olvasta el a dokumentumokat, kommentelte őket és vizsgálta meg munkatársaival és jogászokkal, hogy az üzleti folyamataikba egy-egy megoldás belefér-e.
Elkezdtem kísérletezni azzal, hogy a specifikáció komplett felhasználói folyamatot, történetet ír le (user story), és az hivatkozik az oldaltérkép és a szótár elemeire. Viszont nem volt igazán hatékony megoldás: nagyon egy perszóna user journey-jére fókuszált, viszont sokkal könnyebb volt elképzelni egy-egy felhasználó fontosabb céljának teljesülését. Viszont ez kiegészítő fejezetként (lásd később) remek információ lehet.
És ekkor bukott ki, hogy kell funkcióleírás rész is. Azért kell, mert sok olyan működési elv van, ami felületeken átívelően ugyanúgy vagy nagyon hasonlóan működnek. Miről is beszélek? Vegyünk egy egyszerű funkciót, az új / elfelejtett jelszó igénylését. Az igénylés történhet úgy, hogy a rendszer új jelszót küld e-mailben vagy úgy is, hogy egy tokent tartalmazó linket kiküldve egy jelszóváltoztató oldalra viszi az igénylőt. Ez két eltérő mechaniznus, több felületről is meghívhatjuk, de nem szerencsés, ha ezeken a felületeken másképp működne a funkció. Ezért ezt a funkciót egy a funkciókat bemutató fejezet alpontjaként részletezem. Ez a leírás ráadásul a szótár fogalmait is tartalmazza, sőt hivatkozik is rájuk: jelen példánál maradva a Felhasználó e-mail, jelszó, jelszótoken leírásokra melyek mind-mind ki vannak fejtve, hogy micsodák.
Egyszerű és nagyszerű.
4. A BEVÁLT RECEPT
2014-ben járunk, továbbra is Wordben szerkesztek kereszthivatkozással csak a layoutot csinosítgatom.
A következő pontokból áll a specim:
- Brief (kinek, miért és milyen koncepciót) és fejlesztési környezet (pl. szerver, OS…stb.) — ez maradt ahogy volt
- Fogalmak: ezek írják le egy résztvevő vagy elem jelentőségét és mutatják be a limitációikat (később az adattípusokat és a lehetséges hibaüzeneteket is jelölik)
- Felületek (Oldalak és modulok): ezek mutatják be egy oldal vagy modul felépítését, hivatkozva a fogalmakból.
- Funkciók: élményszerűen vagy tárgyilagosan mutatnak be egy-egy működési logikát, építkezve a fogalmakból és kitérnek az egyes esetekre is.
- User story: a legfontosabb élő példák összegyűjtve, a speci elemeiből építkezve.
Az egyes fejezetekről részletesen a következő cikkemben foglalkozom.
Nem utolsó sorban minden részleg megtalálja benne a számára releváns információt:
- Fogalmak = Backend fejlesztők(adatbázis) és picit Frontendesek a validációk miatt
- Funkciók = Stakeholderek, Backend dev, vagy ebből készülhet az üzleti logika
- Felületek = Stakeholderek, Designerek és Sitebuilderek
Emlékszel, hogy korábban írtam, hogy fejlesztőknek szóló üzleti logikát is tervezett az elődöm? Az üzleti logika írja le az alkalmazás elemeinek egymással való kommunikációját (félig) fejlesztői nyelven. A specifikáció ugyanezt az üzleti logikát tartalmazza emberi nyelven. A megrendelő is erre bólint rá, hiszen érti.
A funkcionális specifikáció lehet akár technikai is, de mivel a célja az, hogy mind a megrendelő, mind a fejlesztő tudja, hogy mi legyen az eredmény, érdemes egyszerűen tartani.
5. ESZKÖZÖK AMIKET PRÓBÁLTAM
Nagyon sok eszközt kipróbáltam és rengeteg munkaórám bent bele, hogy akár feleslegesen megírva, majd a preferált eszközben újraírva a dokumentációt.
5.1. A bevált eszközök
- Microsoft Word — a Word elterjedtsége és az alap (fapados) kereszthivatkozási képessége miatt az egyik legkönnyebben elérhető eszköz, de nagyon fapados. Létezik hozzá egy állati jó plugin (DocTools CrossReferenceManage), ami közel tökéletesre emeli a Word hivatkozási funkcióját. Erről picit részletesebben írtam egy későbbi cikkemben.
- Notion.so — én újhullámos vagy blokkos szövegszerkesztőnek hívom, mert blokkokat írsz és szerkesztesz, amiket aztán ide-oda tudsz pakolgatni. 2016-ban indult, de én 2018 márciusában a Notion 2.0-nál csatlakoztam be. Ezt használom rendszeresen, és I-MÁ-DOM! Erről picit részletesebben írok a cikksorozat 3. részében.
- Docmenta — Single Source Publishing rendszer és ha van olyan ismerősöd, aki tud JAVA-t telepíteni, akkor a telepített rendszer egy erős bronzérmes a sorbab. Kb. fél évig használtam, amíg a Notion-ra rá nem találtam. Nagyon 2005 feelingje van az egésznek, de ahhoz képest, hogy open-source nagyon összetett és profi rendszer, szokni kell a deployment rendszerét, de ha ráérzel a verziókövetése is remek. A cikk írásának pillanatában nem elérhető a szerver, remélem nem állt le a fejlesztése, mert aki teheti és szeretne dokumentációkat írni, az próbálja ki.
5.2. A nem bevált eszközök
Nagyon sok specializált XML DITA Authoring és CCMS megoldást kipróbáltam és ezen kívül a klasszikusabb Wiki rendszereket is megvizsgáltam. A teljesség igénye nélkül ezekről volt feljegyzésem magamnak a múltból.
Wiki platformok
Ezek állnak a legközelebb az elképzelésemhez, de egyik sem vált be.
- Wordpress pluginekkel: YadaWiki, Encyclopedia, Knowledge Base, WP Glossary
- Mediawiki: ez olyan, mint a Wikipedia motorja és még fejlesztik. Ha a Wikipediát szereted szerkeszteni, ezt is szeretni fogod, nekem nem jött be. Van hozzá Visual Editor és Parsoid kiegészítő is amivel elvileg majdnem olyan lenne, ami nekem kéne, de azt nehéz telepíteni.
- Dokuwiki: elsőre jónak tűnt, majd egyre több hiányosságba ütköztem
- PMWiki és Wikkawiki: olyan, mint a Mediawiki, kisebb a támogatottsága, hamar elvérzett.
XML DITA Authoring és CCMS progik
Jellemzően ezekben írják a használati útmutatókat, de amilyen robosztusak, olyannyira nem tudják az egyszerű hivatkozási lehetőséget más fejezetekre, ráadásul az ipari sztenderd (Framemaker, Robohelp, Madcap, OxygenXML) piszok drágák. Pár óránál tovább nem használtam őket.
Egyéb
- Atlassian Confluence — ezt nagyon régen próbáltam egy projekt erejéig még 2014 derekán, ahol JIRA-t használtunk, de hamar elvérzett, mert akkor nem tudta a dinamikus szerkesztést (vagy nem úgy ahogy kényelmes lenne). Elképzelhető, hogy a friss változat nagyon sokat fejlődött, ha lesz lehetőségem újrapróbálom a közeljövőben.
5.3. Érdekesek lehetnek még
6. Jelenkori kísérletezgetések
Érdekes lehet ha a funkciók vagy a user storyk leírását a BDD (Behavior-Driven-Development), azaz a viselkedésalapú fejlesztés irányelvek szerint írjuk meg. Ebben az esetben a Cucumber / Gherkin nem túl bonyolult nyelvét használhatjuk, ráadásul lehetőségünk van akár magyarul is megfogalmazni. Ha így teszünk és tartjuk a megfelelő formátumot, ráadásul a fejlesztők is fel vannak erre készülve, akkor a QA folyamatokat fel lehet gyorsítani, de még jobb, hogy a stakeholderek is érteni fogják, hogy mit fog tudni a funkció. Erre a megoldásra jelenleg még nincsen releváns tapasztalatom, de amint lesz értelme, írok róla egy későbbi cikkben.
Ezen kívül a szervezet számára fontos a célok meghatározása és a specifikáció írásakor ezt figyelembe kell venni. Éppen ezért a specifikációt kiegészítettem egy új ponttal, ami a Célokat mutatja be: mi a felhasználó és cégünk célja az egyes funkciók használatával, tehát azokhoz szorosan kapcsolódik. Ez inkább stratégiai bemutatás, de segíti a gondolkodást és on trackben tartani a projektet, terméket.
Nincs még vége…
A következő cikkben azt mutatom be, hogy pontosan milyen logika és módszertan szerint javaslom a felépítést és az egyes fejezetek milyen információt tartalmazzanak.
