Így írj te is érthető funkcionális- és termékspecifikációkat — Wikispeci (2. rész)

avagy hogyan lehet egyszerű és örömteli az, amit a legtöbb UX-es és PM gyűlöl.

Ez a 2. 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

Ebben a részben bemutatom a Wikispeci felépítését és az egyes fejezetek jellemzőit. Célom, hogy a cikk végigolvasása után, bátra csapj bele te is a specifikálás izgalmas világába.

Jelen cikk angol nyelvű verziójához készítettem egy Notion sablont, amit itt találsz meg: https://www.notion.so/wikispecsample/WikiSpec-Sample-Documentation-8a8fd91a030b40389c711a0d827885a2

TARTALOMJEGYZÉK

1. Mi a WikiSpeci
2. A Wikispeci alapjai
3. A Wikispeci felépítése
4. A Wikispeci felépítésének előnye
5. Végszó, tanácsok

1. MI A WIKISPECI?

Lényegében egy olyan specifikációírási módszertan, amit az évek során fejlesztettem ki és használom a mai napig komolyabb rendszer összefüggésének átgondolására. Olvasd el a kialakulásának történetét itt.

A kulcseleme a rendszerben való gondolkodás, a modularitás és következetesség.

A wikispeci könnyen beilleszthető a lean és az agilis projektvezetési módszertanokba is, hiszen modularitása és következetessége miatt akár folyamatos, akár megszakításos tervezés során alkalmazható. Könnyen alkalmazható az egyes követelmény specifikációk, dokumentációk készítésére is, mint az BRS, FRS, SRS…stb.

A legjobban akkor működik, ha drótváz vagy prototípus mellé készül, mivel a vizuális terveken sokszor nem egyértelmű, hogy mi mivel van összefüggésben, milyen adatokat várunk vagy az adott bekérendő adat ugyanaz az adat-e, mint amit máshol kérünk be. Ezekre a kérdésekre a választ egy összetett prototípus is tartalmazhatja, de abban előfordulhat következetlenség (elfejtünk valamelyik oldalon átírni egy validációs szabályt) vagy egyszerűen minden elemét a felületnek végig kell nyomogatni. Így pl. egy feladat óraszámainak megbecsléséhez nem kell a becslőnek megtalálnia vagy kitalálnia a működési logikát - feltéve ha a UX designer a prototípuson nem dokumentált / kommentelt le mindent pontosan.

2. A WIKISPECI ALAPJAI

#1 lényeg: Következetes szóhasználat és hivatkozás

A Wikispeci egyik lényege az, hogy ne legyenek összevissza elnevezések: ha valamilyen fogalomnak, felületnek vagy funkciónak kitaláltunk egy nevet, akkor legyen mindenhol ugyanaz a neve. Gondolj erre úgy, hogy ha nem lennének linkek, akkor is tudja az olvasó, hogy mire gondolsz amikor utalsz egy másik pontra.

Viszont a dokumentáció írójától nem feltétlen várható el, hogy a kitalálás pillanatában a tökéletes elnevezést találja ki, így az később változni fog.

Nézünk egy példát: a Fogalmak ponton belül létrehozol egy “User” pontot, mert nem jut eszedbe a “Felhasználó” szó. Erre a pontra hivatkozol egy funkció vagy felület bemutatásában. Viszont később kiderül, hogy használjuk magyarul a fogalmat és megváltoztatod Felhasználóra. Ha nem frissül le a dokumentumban mindenhol a User szó Felhasználóra, akkor könnyen azt gondolhatja az olvasó, hogy ez két külön dolog.

Gondolhatjuk azt, hogy “Keresés & Csere” (Search & Replace) funkcióval egyszerűen csak felülcsapom mindenhol a User szavunkat, de mi van akkor, ha valahol máshol is szerepel a User szó csak más kontextusban. Így fordulhat elő olyan eset, hogy ahol a User Experience kifejezést használtuk a szovegben, végül Felhasználó Experience lesz a tömeges módosítást követően.

A legjobb megoldás erre, ha olyan eszközt használunk az íráshoz, ami támogatja a dokumentumon belüli dinamikus kereszthivatkozást.

A javasolt eszközökről egy picit lejjebb beszélek.

#2 lényeg: Modularitás

A Wikispeci másik alapja a modularitás: amit lehet bontsuk külön pontokra és ezeket a pontokat hivatkozzuk egymásra. Ezt sok ember nem szereti olvasni, viszont így tud konzekvens maradni minden mindennel.

3. A WIKISPECI FELÉPÍTÉSE

A következetesség és a modularitás miatt a Wikispeci fejezetekből, alpontokból és azok elemeiből épül fel. A legfontosabb fejezetek a Fogalmak, Felületek, Funkciók (3F), minden más “csak” kiegészítés vagy segíti (pl. célok és felhasználói történetek).

A 3F fejezetek sorrendje lehet más, pl. Felületek, Funkciók, Fogalmak is, főleg ha blokk alapú online szövegszerkesztőt használsz (pl. Notion, lásd később).

WikiSpeci kezdőoldala, rajta a fő fejezetek (WikiSpeci Notion példasablon)

1. fejezet: BRIEF

Kötelező.

Röviden bemutatja, hogy kinek és miért készül a projekt, valamint tartalmazhatja külön vagy alfejezetekben, hogy mi a fejlesztési környezetet (fejlesztési nyelv, szerveroldali scriptek és verziószámaik, szerver környezet…stb.).

2. fejezet: CÉLOK, EPICEK

Opcionális, de nagyon-nagyon ajánlott.

2021. évi frissítés: a példasablonban ez a brief fejezet része már, de nyugodtan szétbontható.

Bemutatja, hogy mi a szervezet, megrendelő vagy a projekt célja a készülő termékkel, illetve a használók milyen feltételezett utakon fogják használni a készülő rendszerünket.

Lényegében ez a Brief fejezetben foglaltak stratégiai kifejtése és összefoglalja, hogy egy adott szereplőnek mi a célja egy vagy több funkcióval, illetve ez milyen kihatással van a rendszerre vagy a szervezetünk üzleti céljára.

Ha a SCRUM projektvezetési keretrendszert követjük ez lényegében egy ún. epic, ami több user storyt, rövidebb történetet (tehát funkció leírást, lásd később) foglal magában, így egy vagy több komplett felhasználói történetét mesél el egyben.

Lássunk egy nagyon leegyszerűsített, de komplex példával:

“A [felhasználó] azért végzi el a [felhasználói bejelentkezés]t a [bejelentkező felület]en, hogy további [regisztrációhoz kötött funkciók]hoz férjen hozzá. Szervezetünk [tulajdonosai]nak célja, hogy a bejelentkezők száma az adott napon a forgalom 10%-a legyen, melyet az [riportálás] admin felületen a [napi bejelentkező arány] szekcióban lehet nyomon követni. A számok teljesülése esetén a [perszonalizált hirdetésmegjelenítések] a bevételeink napi 2%-át fedezik. Ha a számok nem teljesülnek, a [hibanapló] admin felületen ellenőrzi a [termékmenedzser], hogy milyen eset hátráltatta azt.”

A fenti példában a keretes zárójelben megfogalmazottak a specifikáció adott pontjára (fogalom, felület, funkció — 3F) mutatnak, de hivatkozhatnak akár egy Analytics linkre is, ahol bejelentkezve már látszódnak az információk.

Ennek és Funkció fejezetnek (lejjebb) a másik előnye, hogy lényegében már egy közel kész felhasználói kézikönyvet is írunk.

A fenti példában még olyan információk is megjelennek, mint:

• A cél felelősei akiknél felmerült az igény vagy aki figyelni fogja a teljesülést (pl. “tulajdonos”, “termékmenedzser”);
• Mindez hogyan segíti az üzleti céljainkat (pl. “perszonalizált hirdetésekből folyó bevétel”) — ez nagy segítség a a projekttervezésnél a feladatok priorizálásában;
• Mi a cél teljesülésének a mérőszáma (pl. “napi 10% sikeres bejelentkezés”)

Ez elsősorban a döntéshozóknak készül, de a backend fejlesztőnek is hasznára válik.

3. fejezet: FOGALMAK

Kötelező.

3F első eleme, ami bemutatja az összes résztvevőt (pl. felhasználók, adminisztrátor és azok típusait) és az egyes elemek tulajdonságait (pl. terméktulajdonságok). Én adatbázisnak nevezem, mert ahogy egy adatbázisban meghatározhatod, hogy mik a korlátai egy adott elemnek (10 karakter, csak angol ABC betűi…stb.) úgy itt is ez kerül kifejtésre és érdemes egy példa adatot itt megjeleníteni.

Jellemzően a backend fejlesztők és a felületi elemek validációjnak feltétele miatt frontend fejlesztők fogják használni.

Egy fogalom részei:

• Fogalom neve (Pl. “Regisztrált felhasználó”)
• Leírása (Pl. “A regisztrált felhasználók hozzáférnek a regisztrációhoz kötött funkciókhoz.”, ahol már hivatkozhatjuk is a funkciót)
• Fogalom részei, elemei (Pl. Felhasználó keresztneve, email címe, jelszó, Social ID…stb) Ezek mind külön fogalomként viselkednek, hogy később ezekre is hivatkozhassunk.
• Elemek tulajdonsága (karakterlimitek, példa adat, megjegyzés, beviteli mező esetén hibaüzenetek…stb.)
• Esetleges típusai (pl. Látogató, Vendég felhasználó, Regisztrált felhasználó… stb.)

Érdemes csoportosítani az összefüggő adatokat.
Példa egy általános felhasználói adatok csoportosítására:
1. Felhasználó

1.1. Felhasználó típusa
1.1.1. Látogató
1.1.2. Vendég felhasználó
1.1.3. Regisztrált felhasználó

1.2. Felhasználó adatai
1.2.1. Felhasználó neve
1.2.1.1. Felhasználó vezetékneve
1.2.1.2. Felhasználó keresztneve
1.2.2. Regisztrált felhasználó email cím
1.2.3. Regisztrált felhasználó telefonszám
1.2.4. Felhasználó egyedi azonosító
…

1.3. Felhasználó státuszai
1.3.1. Inaktív felhasználó
1.3.2. Aktív felhasználó
1.3.3. Blokkolt felhasználó
1.3.4. Törölt felhasználó

A legmélyebb pontok (“levél” szintű adat) az amelyiknek a tulajdonsága kifejtésre kerül.

Notion — Felhasználói adatok csoportosítására egy példa. Minden “adat neve” és táblázat cím a speci különböző pontjairól hivatkozható.

Notion — Példa a felhasználói azonosító bemutatására. Az adott rekord hivatkozható a speci bármelyik pontjáról.

Érdemes élni a csoportosítás lehetőségével, főleg ha egy vagy több adat később többször együtt kerül megemlítése. Pl. sok esetben a vezetéknév és a keresztnév együtt szerepel, ezért ha valahol hivatkozunk a felhasználó nevére, akkor az már belefoglalja a vezeték és a keresztnevet is azok tulajdonságait. A fenti képlopatokon az alapadatok és a hivatalos adatok pl. két külön csoportban vannak, így ahol pl. a hivatalos adatok megadása szükséges, ott elég csak a adott csoportra hivatkoznom nem kell külön az elemekre.

4. fejezet: FELÜLETEK

Kötelező.

A 3F eleme, ami mutatja be egy-egy oldal, felület vagy oldalon belül előforduló szekciók, modulok felépítését.

Ezt a designerek, a frontend fejlesztők és a döntéshozók fogják használni.

A felületek egyes pontjainak részei:

• Kapcsolódó tervek (képek vagy linkek)
• Kapcsolódó funkciók, célok, user storyk
• SEO adatok
• Elemek, azok típusa és a hozzájuk kapcsolódó fogalmak (pl. beviteli mezők) vagy funkciók (pl. gombra kattintva)
• Esetleges korlátozások (milyen felhasználói típus mit lát)

Ha egy-egy oldalnak visszatérő elemecsoportjai vannak azokat érdemes külön pontban kifejteni és azt a felületeken behivatkozni, így biztos, hogy minden oldalon így fog kinézni.

Notion — Bejelentkezési felület bemutatása. Hivatkozás funkciókra fogalmakra.

5. fejezet: FUNKCIÓK, USER STORYK

Kötelező és a legfontosabb fejezet.

A 3F ami koncentrál egy adott eset részletes kifejtésére, a működési logika bemutatására. Történhet akár élményszerűen, akár tárgyilagosan, a lényeg, hogy részletes legyen.

Ezt a fejezetet leginkább a stakeholderek és a backend fejlesztők fogják szeretni, illetve ez a rész tartalmazza a fentebb említett célok / “epicek” részleteit, tehát a történeteket (storykat).

Egy funkció bemutatójának részei, struktúrája:

• Kapcsolódó résztvevők
• Kapcsolódó felületek
• További kapcsolódó funkciók
• Működés bemutatása
• Funkció lehetséges kimenetelei, esetei

Maga a működés leírás ne legyen nagyon hosszú. A tapasztalatom az, hogy ha valami nem fér bele 2000 karakterbe, akkor az már több funkció leírása vagy egy eposz (epic) leírás, ami a 2. fejezet feladata.

Ugyan maga a működés bemutatása tartalmazza a felhasználókat, a felületeket és a kapcsolódó funkciókat, de javaslom külön is kigyűjteni ezeket a tételeket, hogy könnyebben átlátható legyen elsőre is.

A funkció bemutatásának fontos része még a sikeres és sikertelen esetek bemutatása is. Itt meghatározhatjuk, hogy mely funkcióhoz kapcsolódik, pl. egy ellenőrzés, de akár kitérhetünk, hogy milyen üzenet jelenjen meg egy bizonyos eset bekövetkeztekor, ha azokat nem fogalmaztunk meg a Fogalmak részben.

Mivel a projektvezetést segíti a priorizálás, és erre bőven elég a MoSCoW technika 4 kategóriája:

• 🔴 kötelező (vagy magas)
• 🔵 szükséges (vagy közepes)
• ⚪ Jó-ha-van (vagy alacsony)
• ⚫ nem-szükséges.

Ezeket jelöljük a címben emojikkal (pl. körökkel) vagy a cím színezésével, ha azt a szerkesztők támogatja — a lényeg, hogy a funkciók listázásakor ÉS a behivatkozott helyeken is látszódjon, rákattintás nélkül, hogy érdemes-e velük foglalkozni vagy sem.

Funkció / User story leírása

Ha agilis környezetben dolgozunk, akkor ezeket a user storykat lehetőségünk van User Story Mapping mátrixba is rendezni. Ez a táblázat mutatja be a felhasználó általános “haladási” irányait és a lehetőségeit nagyobb csoportokba rendezve (pl. Bejelentkezés, Keresés).

Ha Notiont használunk, akkor lehetőségünk van létrehozni a felületeken belül egy ún. inline boardot (beágyazott táblázat), amivel kártyákra tudjuk gyűjteni a bejegyzéseket és rendszerezni azokat a táblázat egyes lépéseibe, sőt tovább csoportosíthatjuk ezeket Releasek (kiadások) szerint.

4. STÁTUSZOK JELZÉSE A BEJEGYZÉSEKBEN

Ahogy a Funkcióknál említettem a priorizálast, úgy minden egyes különálló oldalnál / bejegyzésnél amire hivatkozni lehet, érdemes jelölni a címben, hogy az milyen státuszú. Erre 3 jelző elég és használhatunk emojit (ügyeljünk arra, hogy ne legyen azonos a funkciók priorizálására használttal, ezért legyenek itt zászlók):

• Nincs elkezdve: 🏴
• Folyamatban: 🏳️
• Befejezve: 🏁

Ha többen is szerkesztitek bevezethettek egy Ellenőrzésre 🎌 státuszt is.

Ha színesebbet szeretnénk, akkor a következőket javaslom:

• Nincs elkezdve: ⏹️ (stop gomb)
• Folyamatban: 🚧
• Befejezve: ✔️

Mivel előfordul, hogy elfelejtjük jelölni a státuszt, ezért a befejezett dolgokra is alkalmazzunk emojit. Ezzel látni fogjuk, ha valamilyen funkció előkészítéséről megfeledkeztünk, vagy legalábbis dolgunk van vele.

Ami még fontos lehet, ha egy adott bejegyzést törlésre jelölsz, így pl. könnyebben kiszűrhető a dokumentum olvasásakor, ha már nem élő pontra hivatkozunk. Erre használjuk bátran a kuka emojit: 🗑️ vagy a feltűnőbb piros ❌ jelet.

5. A WIKISPECI FELÉPÍTÉSÉNEK ELŐNYE

Mivel a wikispeci moduláris, tehát fejezetekből építkezik, ezért nagy előnye, hogy ha elakadnál a tervezésben, mindig valamelyik fejezet ötletet ad, hogy hogyan lehet kiegészíteni vagy pontosítani a dokumentumot.

Van aki a funkciók megírását szereti jobban, de van aki a felületeket szereti összefoglalni, vagy könnyebb neki User Storykban vagy célokban gondolkodni. Ezek a fejezetek tartalmazzák a fogalmakat is, így ha a megfogalmazás során nincs meg egy fogalom, akkor az rögtön létrehozhatod és a limitációi kifejtésre kerülhet.

Pl. bejelentkezés felület információs architektúráját írod össze a Felület fejezetben, de ha nincs, akkor nem fogod tudni belinkelni a “felhasználó jelszó” fogalmat, így azt létrehozod a Fogalom fejezeten belül és kifejted. Ez jellemzően azt generálja, hogy eszedbe jut még felhasználóhoz köthető egyéb adat, fogalom. Ha nem akkor lehet folytatni a felület bemutatását és kapcsolódó Funkciók leírását. A lényeg, hogy jellemzően a specifikációban az alapként tekinthető 3F fejezetek (Fogalmak, Felületek és a Funkciók) “karbantartása” lényegében egymás tartalmait generálják. Ha tényleg nem tudsz már sehova sem írni semmit, akkor közel jársz már a tervezés végéhez.

6. Végszó, tanácsok

Remélem most már te is kedvet kaptál a specifikációk írására és hatékonyan tudod alkalmazni a jövőben a gondolatokat. A Wikispeci nem mindenható, nagyon sok megszokást igényel a gondolatmenete, viszont hosszútávon az tapasztalatom, hogy beválik, mert az összefüggések kezelése nagyon leegyszerűsödik.

Ha érdekel, hogy milyen eszközökkel érdemes írni, olvasd tovább a cikksorozat 3. részét.

Ha szeretnél még részletesebb dokumentációt írni vagy csak érdekel, hogy a folyamatokat hogyan lehet folyamatábrán vizualizálni, olvasd el a BPMN szabályrendszerről szóló cikkemet is.

Ha tetszik a cikk, kattints egy párszor a cikk bal oldalán megjelenő taps ikonra! 😉