Kaip rašyti užklausas DI programėlių kūrimo įrankiams (su prieš ir po pavyzdžiais)

Gera užklausa DI programėlių kūrimo įrankiui apibūdina produktą, o ne kodą: kas jį naudoja, ką žmonės daro žingsnis po žingsnio, kokius duomenis jis saugo ir kam leidžiama ką matyti. Kai pirmoji versija jau yra, prašyk vieno konkretaus pakeitimo kiekvienoje žinutėje, pasakyk, kas turi likti tas pats, ir problemas aprašyk kaip „Aš padariau X, tikėjausi Y, gavau Z“. Šie trys įpročiai ištaiso daugumą nusivylimą keliančių rezultatų.

Likusioje šio vadovo dalyje detaliai parodyti šablonai su prieš ir po pavyzdžiais, kuriuos gali pritaikyti.

Kodėl užklausa programėlių kūrimo įrankiui skiriasi nuo pokalbio su DI

Kai klausi pokalbio asistento, neaiški užklausa duoda neaiškų atsakymą, ir tu eini toliau. Kai užklausi DI programėlių kūrimo įrankį, atsakymas yra veikianti programa. Kiekviena tavo aprašymo spraga užpildoma spėjimu, o tie spėjimai tampa kodu, duomenų bazių lentelėmis ir ekranais, kuriuos tada turi pakęsti arba pašalinti.

Todėl užklausos tikslas nėra skambėti protingai. Tikslas – palikti kuo mažiau svarbių sprendimų atsitiktinumui. Techninio žodyno tam nereikia. Reikia būti konkrečiam dėl dalykų, kuriuos žinai tik tu: savo naudotojų, darbo eigos ir taisyklių.

Ką įtraukti į pirmą užklausą

Prieš rašydamas bet ką, atsakyk į šiuos klausimus. Kiekvienas uždaro spragą, kurią DI kitu atveju spėtų.

Įtrauk	Kodėl tai svarbu	Pavyzdys
Produktą vienu sakiniu	Nustato rėmus visiems vėlesniems sprendimams	„Rezervacijų svetainė dviejų kėdžių kirpykla“
Kas naudoja	Nulemia ekranus ir toną	„Klientai be rezervacijos telefonuose ir savininkas nešiojamame kompiuteryje“
Pagrindinį srautą žingsnis po žingsnio	Tai, kas turi veikti pirmiausia	„Pasirink paslaugą, pasirink laiką, įvesk vardą ir telefoną, gauk patvirtinimą“
Duomenis, kuriuos saugo	Tampa duomenų bazės struktūra	„Paslaugos, rezervacijos, klientai“
Kas ką gali matyti ar keisti	Nulemia prisijungimą ir teises	„Tik savininkas mato visas rezervacijas“
Išvaizdą ir jausmą, trumpai	Išvengia bendro numatytojo stiliaus	„Tamsus, paprastas, dideli mygtukai“
Ką palikti kol kas	Išlaiko pirmą versiją mažą	„Kol kas be mokėjimų ir atsiliepimų“

Paskutinė eilutė įvertinama per mažai. Pasakymas, ko nenori, neleidžia DI pridėti tinklaraščio, kainų puslapio ir naujienlaiškio prenumeratos, kurių niekada neprašei.

Prieš ir po: pirma užklausa

Prieš:

Padaryk man programėlę savo sporto klubui.

Įrankis turi viską spėti: ar nariai, ar darbuotojai? Grupinės pamokos ar asmeninės treniruotės? Mokėjimai? Gausi kažką, kas atrodo kaip sporto klubo svetainė ir nedaro to, ko tau reikia.

Po:

Sukurk pamokų rezervavimo programėlę mažai jogos studijai. Nariai mato šios savaitės pamokas (pavadinimą, mokytoją, laiką, laisvas vietas), rezervuoja vietą ir gali atšaukti likus ne mažiau nei dviem valandoms. Nariai registruojasi el. paštu ir slaptažodžiu. Studijos savininkas prisijungia, kad pridėtų pamokas, matytų, kas užsirašė, ir pažymėtų dalyvavimą. Saugok pamokas, narius ir rezervacijas duomenų bazėje. Ramus, šviesus dizainas, gerai veikiantis telefonuose. Mokėjimų kol kas nėra.

Antroji versija vis dar trumpa. Ji tiesiog atsako į klausimus iš lentelės aukščiau.

Aprašyk elgesį, o ne įgyvendinimą

Dažnai geresnius rezultatus gausi aprašęs, kas turi nutikti, o ne kaip tai sukurti.

Prieš:

Pridėk useEffect, kuris paima rezervacijas, ir modalinį komponentą redagavimui.

Po:

Kai savininkas paspaudžia rezervaciją, atidaryk skydelį, kuriame jis gali pakeisti laiką arba ją atšaukti. Pakeitimai iš karto turi matytis sąraše.

Pirma užklausa priverčia DI naudoti konkretų metodą, kuris gal netinka, kaip programėlė sukurta. Antra pasako rezultatą ir leidžia DI pasirinkti tinkamą būdą jau parašytam kodui. Jei esi kūrėjas ir turi stiprų pageidavimą, pasakyk jį, bet kartu nurodyk rezultatą.

Būk konkretus dėl taisyklių

Verslo taisyklės – tai vieta, kur DI sukurtos programėlės dažniausiai klysta, nes jos akivaizdžios tau ir nematomos DI. Išdėstyk jas aiškiai.

Ribos: „Narys gali turėti ne daugiau kaip tris būsimas rezervacijas.“
Laikas: „Atšaukimai užsidaro likus dviem valandoms iki pamokos pradžios.“
Kraštutiniai atvejai: „Jei pamoka pilna, rodyk mygtuką Į eilę vietoj Rezervuoti.“
Teisės: „Mokytojai mato savo pamokų dalyvavimą, bet ne kitų mokytojų.“

Kiekviena iš jų – vienas sakinys. Jei bet kurią praleisi, programėlė arba nepritaikys taisyklės, arba išgalvos savo versiją.

Po pirmos versijos: vienas pakeitimas žinutėje

Kai kažkas veikia peržiūroje, pereik nuo viso produkto aprašymo prie prašymų dėl mažų, patikrinamų pakeitimų.

Prieš:

Dizainas nukrypęs, rezervacija tinkamai neveikia, ir noriu kalendoriaus rodinio bei el. laiškų.

Po (keturios atskiros žinutės):

Kai rezervuoju paskutinę vietą pamokoje, pamoka vis dar rodo „Liko 1 vieta“. Turi rodyti „Pilna“ ir slėpti mygtuką Rezervuoti.

Pridėk savaitės rodinio kalendorių tvarkaraščio puslapyje, po vieną stulpelį kiekvienai dienai. Palik dabartinį sąrašo rodinį kaip pasirinkimą.

Padaryk pamokų kortelėms kompaktiškesnes telefonuose: mažesni tarpai, mokytojo vardas toje pačioje eilutėje kaip laikas.

Išsiųsk nariui patvirtinimo laišką, kai jis rezervuoja.

Kodėl tai veikia:

Kiekvienas pakeitimas pakankamai mažas, kad DI jį teisingai atliktų vienu bandymu.
Gali patikrinti kiekvieną prieš judant toliau.
Jei vienas nepavyksta, gali grąžinti tik tą žingsnį nepraradęs kitų.

Pasakyk, ką išlaikyti

Kai prašai pakeisti tai, kas jau veikia, pasakyk DI, ko keisti negalima. Tai vienas lengviausių būdų sustabdyti regresijas (dalykus, kurie anksčiau veikė, bet nutrūko po redagavimo).

Perkurk pagrindinio puslapio viršutinę dalį su didesniu antraštė ir nuotrauka dešinėje. Palik navigaciją, spalvas ir viską po viršutine dalimi tiksliai taip, kaip yra.

Tas pats galioja duomenims: „Pridėk narių telefono numerio lauką. Nepašalink ir nepervardink jokių esamų laukų.“

Naudok ekrano nuotraukas ir tikslų tekstą

Žodžiai kaip „dalykas viršuje“ yra dviprasmiški. Dauguma DI programėlių kūrimo įrankių priima nuotraukas, o ekrano nuotrauka su trumpa pastaba yra greitesnė nei pastraipos aprašymas.

Pridėk ekrano nuotrauką ir parašyk „mygtukas, apibrauktas raudonai, telefonuose persidengia su meniu“.
Įklijuok tikslų klaidos pranešimo tekstą, o ne perfrazuok.
Cituok ekrane matomas etiketes tiksliai: „mygtukas Išsaugoti pakeitimus Nustatymų puslapyje“.

Specialiai klaidoms naudok tokią formą:

Rezervacijų puslapyje paspaudžiau Atšaukti rezervacijai rytojui. Tikėjausi, kad ji dings iš mano sąrašo. Vietoj to nieko neįvyko, ir rezervacija vis dar yra po puslapio atnaujinimo. Ištaisyk ir patikrink, kad atšaukimas veikia.

Mūsų vadovas apie kaip ištaisyti DI sukurtą programėlę šią temą nagrinėja plačiau.

Dideliems pakeitimams pirma planuok

Bet kam, kas liečia daug programėlės dalių – pridedant naudotojų paskyras programėlei, kuri jų neturėjo, pridedant mokėjimus, keičiant, kaip saugomi duomenys, – prašyk plano prieš bet kokį kodo keitimą.

Prieš ką nors keisdamas paaiškink, kaip pridėtum komandos paskyras: kokios naujos lentelės, kurie puslapiai keičiasi ir kas nutinka esamiems naudotojams. Kol kas nekeisk kodo.

Perskaityk planą. Jei jis ką nors nesupranta, vienos pastraipos ištaisymas kainuoja gerokai mažiau nei baigtos funkcijos taisymas. Daugelis įrankių turi specialų režimą tam; Mythex tai yra Plan režimas, kartu su Build ir Ask.

Ko vengti

Venk	Kodėl	Vietoj to
„Padaryk geriau“ / „Padaryk, kad išsiskirtų“	Nėra tikslo, todėl DI keičia dalykus atsitiktinai	Įvardyk pakeitimą: „daugiau tarpų tarp skyrių, didesnės antraštės“
Vieną milžinišką užklausą su dešimčia funkcijų	Klaidos kaupiasi; sunku testuoti	Viena funkcija vienoje žinutėje
API raktų įklijavimas į pokalbį	Raktai patenka į pokalbio istoriją	Naudok įrankio paslaptis arba aplinkos nustatymus
Ginčas dėl sugedusio rezultato	Kiekvienas pataisymas užkrauna klaidą	Grįžk atgal ir perfrazuok
Kodo, kurio nesupranti, nurodymas	Įtvirtina prastą tinkamumą	Aprašyk norimą elgesį
Prašymas „įmonės lygio saugumo“	Nieko konkretaus nereiškia	Išvardyk tikras taisykles: kas ką gali matyti

Dėl API raktų: jei reikia mokėjimų ar el. pašto paslaugos, įdėk jos raktus į projekto paslaptis, o ne į užklausą. Jei tai nauja, žr. kas yra aplinkos kintamieji ir paslaptys.

Pakartotinai naudojami užklausų šablonai

Pritaikyk juos pakeisdamas laužtiniuose skliaustuose esančias dalis.

Nauja programėlė:

Sukurk [programėlės tipas] skirtą [kam]. Jie [pagrindinis srautas žingsnis po žingsnio]. [Antras naudotojų tipas] prisijungia, kad [ką daro]. Saugok [duomenys] duomenų bazėje. [Išvaizda ir jausmas]. Palik [dalykai vėlesniam laikui].

Nauja funkcija:

Pridėk [funkcija] į [puslapis]. Kai [naudotojas] atlieka [veiksmas], [kas turi nutikti]. Tik [kas] gali [tai daryti]. Palik [esami dalykai] tokius, kokie yra.

Dizaino pakeitimas:

Puslapyje [puslapis] pakeisk [konkretus elementas] į [konkretus pakeitimas]. Palik [ką išlaikyti]. Patikrink, kad atrodo teisingai telefono pločio ekrane.

Klaida:

Puslapyje [puslapis] padariau [žingsniai]. Tikėjausi [tikėtina]. Vietoj to [tikrasis rezultatas, plius tikslus klaidos tekstas]. Ištaisyk ir patikrink, kad srautas veikia.

Klausimas be pakeitimų:

Nekeisk jokio kodo. Paaiškink, kaip veikia [programėlės dalis] ir kur saugomi [duomenys].

Ilgesnės specifikacijos rašymas

Didesniems projektams gali padėti pirma parašyti vieno puslapio brifą ir įklijuoti jį kaip pradinę užklausą: naudotojus, pagrindinius srautus, duomenis, taisykles ir tai, kas neįtraukiama. Gali net pasitelkti DI juodraščiui parengti – mūsų vadovas apie produkto reikalavimų dokumento rašymą su DI parodo, kaip. Tik laikyk pirmą kūrimo užklausą pagrindiniam srautui ir likusius pridėk žingsnis po žingsnio.

Užklausos Mythex

Visa aukščiau aprašyta veikia Mythex. Keli konkretūs dalykai padeda:

Build, Plan ir Ask režimai. Naudok Plan dideliems ar rizikingiems pakeitimams, o Ask, kai nori paaiškinimo be redagavimų.
Kontrolės taškai. Po kiekvieno sėkmingo pakeitimo Mythex išsaugo kontrolės tašką, o Revert to this point ties atsakymu grąžina projektą atgal. Taip pat gali redaguoti ankstesnę žinutę ir ją iš naujo išsiųsti, kad nuo to taško išbandytum kitą užklausą.
Paslapčių kortelė. Kai agentui reikia API rakto, jis paprašo per kortelę pokalbyje, todėl reikšmė išsaugoma kaip projekto paslaptis, o ne įrašoma į tavo žinutę.
Nuotraukos. Pridėk ekrano nuotraukas ar maketus, ir agentas jas pažiūrės.

Dokumentacijoje yra trumpas puslapis apie veiksmingas užklausas ir vienas apie iteravimą be perkūrimo. Jei pradedi nuo nulio, kaip sukurti programėlę su DI aprašo pilną projektą, o kaip sukurti gerai atrodančią programėlę su DI apima užklausas vizualiniam poliravimui.

Klausimai

Kokia turėtų būti užklausa DI programėlių kūrimo įrankiui?

Pirmai versijai paprastai pakanka trumpos keturių–aštuonių sakinių pastraipos: kas naudoja programėlę, pagrindinis srautas, duomenys, kuriuos ji saugo, ir kas ką gali matyti. Vėliau geriau veikia trumpos užklausos, prašančios vieno pakeitimo vienu metu, nei ilgos.

Ar turėčiau DI pasakyti, kokią sistemą ar kalbą naudoti?

Tik tada, jei turi priežastį, pavyzdžiui, kūrėją, kuris perims kodą, arba paslaugą, kuri veikia tik su viena technologija. Kitu atveju aprašyk produktą ir leisk kūrimo įrankiui pasirinkti protingus numatytuosius nustatymus.

Kodėl DI nuolat keičia dalykus, kurių neprašiau keisti?

Dažniausiai todėl, kad užklausa buvo plati („pagerink“) arba nenurodė, ką išlaikyti. Įvardyk tiksliai, ką keisti, pasakyk, kas turi likti tas pats, ir prašyk vieno pakeitimo kiekvienoje žinutėje.

Ar geriau ištaisyti blogą rezultatą papildomomis užklausomis, ar pradėti iš naujo?

Jei paskutinis pakeitimas viską pablogino, grįžk prie versijos prieš jį ir perfrazuok, o ne kraukk pataisymus vieną ant kito. Naują projektą pradėk tik tada, kai pati idėja pasikeitė.