Brukerdokumentasjon Brukerdokumentasjon
Forord Dette dokumentet skal belyse kravene til systemet og hvordan de ble utformet og etterlevet. Siden prosjektet er utviklet etter Scrum-modellen, er dette ikke en klassisk kravspesifikasjon, men skal vise hvordan behovet for denne type oversikt ble oppfylt. Innholdsfortegnelse Forord... Innholdsfortegnelse... Om bakgrunnen... 4 Overordnet systembeskrivelse... 4 Funksjonelle og ikke-funksjonelle krav... 4 Tekniske krav... Krav til dokumentasjon... Krav til kodestandard... Vedlegg Product Backlog... 8
Om bakgrunnen Oppdragsgiveren UDP driver med både konsulentvirksomhet og utvikling av egne salgbare produkter. Idéen til skjemageneratoren ble til under en idémyldring, og var ganske løst formulert da vi begynte på prosjektet. En del av oppgaven vi fikk ble derfor å utforme det endelige produktet. Ønskelisten som vi fikk som utgangspunkt for prosessen er inngår i avsnittet under som handler om funksjonelle og ikke-funksjonelle krav. Overordnet systembeskrivelse Det skal lages et system som skal brukes til å generere spørreskjemaer. Disse skal kunne gjennomføres ikke bare på vanlig PC, men også på håndholdte enheter som for eksempel mobiltelefon. UDP skal kunne administrere rettighetene til kundene som tar i bruk systemet. Kundene skal kunne administrere rettighetene til sine sluttbrukere, opprette spørreskjemaer og se resultatene av disse. Sluttbrukere skal være av to typer. Den ene typen skal bare kunne besvare undersøkelser som er satt opp uten krav til pålogging. Den andre typen skal også kunne besvare undersøkelser som er begrenset av bruker-id og passord. Disse brukere skal kunne lagre halvbesvarte undersøkelser og fortsette besvarelsen på et senere tidspunkt. Funksjonelle og ikke-funksjonelle krav Systemet ble utviklet ut fra følgende dokument fra UDP: Illustrasjon : Systemet skal virke på Opera Mini Følgende informasjon ble skriblet ned under et idémøte vi holdt i forkant av møtet med dere. Dette notatet er sannsynligvis ikke veldig godt strukturert, men vil gi dere et bedre bilde av hva vi forestiller oss. Ta gjerne kontakt med aog@udp.no for avklaringer rundt dette dokumentet. Med vennelig hilsen Espen Schulstad ------------------------ Tanken: en enkel skjemagenerator som er nettbasert. Overordnede funksjoner for Administrasjonsapplikasjonen Vår administreringsdel: -Bedrift håndtering -håndtere brukere -crud+søk av skjema 4
Bedriftersdel: -håndtere brukere -crud+søk av skjema Funksjoner for skjema -templatebasert. vise til css og bildekatalog. -kunne laste opp css til enkelt skjema -enkelt, legge til et spørsmål per side. -routing, mulighet til å få andre spørsmål på neste side. hvis ja gå til side, hvis nei gå til side 4. -holde seg til wc-standard Spørsmålstypene: -Radioknapper -Checkbox -Dropdown -Textfelt -Textarea -Opplasting av fil (med filgrense), kun noen filformater. -Email Tilbakemeldingsdelen: Avslutningsrapport ved registrering av skjema. -utfallet av dine egne svar -utfallet av alles svar -Melding som er redigerbar -Mailtilbakesendelse skal enten gå på personlig bruker Persistering: Personlige skjema - skal lagres til basen. Anonyme skjema: -hvis bruker blir ferdig med spørsmål, skal lagres til basen. -hvis bruker ikke blir ferdig med spørsmål, skal det ikke lagres til basen Personlig del på mobil: Innloggingsside -Tilgjengelige skjemaer -Ufullførte skjemaer, kunne gjenoppta skjema Rapporter -kreve noen formater(pdf, html, xls??) -hva slags? Ikke funksjonelle krav -det skal være sikker pålogging til administrsjonsdelen -det skal være sikker pålogging til porsonlige skjema -språkstøtte for engelsk og norsk i administrasjonsdelen -feilmelding til brukere. du tastet feil. feil format. blankt svar. For stor fil. Systemet er nede. I tråd med Scrum-metoden ble det ut over dette ikke utarbeidet en komplett liste over krav, men en liste ( product backlog ) over de mest sentrale funksjonene som vi så måtte være
med. Denne listen ble så utvidet etter hvert som andre behov viste seg mens vi utviklet systemet. Den endelige listen finnes som vedlegg til denne rapporten. (Vedlegg ) Tekniske krav Følgende tekniske krav ble tidlig avtalt med UDP: På håndholdte enheter skal systemet som minimumskrav fungere på Opera Mini. Administrasjonsdelen skal være platformuavhengig Krav til dokumentasjon Det ble ikke stilt konkrete krav til dokumentasjon, men vi har lagt vekt på at vi skal levere fra oss et system som er lett å vedlikeholde og videreutvikle. Systemet skal være mest mulig selvdokumenterende; dvs dokumentasjonen skal først og fremst ligge i koden i form av velvalgte navn på datafelt, variabler og funksjoner, samt forklarende avsnitt foran de kodeavsnitt som ikke er tilstrekkelig selvforklarende. Krav til kodestandard Vi valgte tidlig en standard for utforming av koden. Denne avviker ikke særlig fra industristandard for Java-kode. Alle kommentarer er skrevet på engelsk Variabel og metodenavn skal også være på engelsk, begynne med liten bokstav, og for øvrig være i camel case (sammenhengende, med storbokstav som ordskillemarkør). Kontrollstrukturer (som if- og for-blokker) skrives uten mellomrom før eller etter parentesene. Alle kommentarer skrives som blokkomentarer (/* */). Linjekommentarer (// ) brukes bare til utkommentering av kode. Tabulator skal brukes, ikke tilsvarende antall mellomrom. class QuestionService def transactional = false /** * Save a Question with options if specified. optionlist will contain all valid Options * if an validation error occurs. optionlist is used for reporting errors to the user * and filling in the form. * * @params question Question to save. * @params options Map passed from the view. * @params optionlist Empty list used for returning of valid options. * @params insert True if we are inserting a new question, false if we're updating. * @returns True if saving was successful. */ public boolean savequestion(question question, Map options, List optionlist, boolean insert = true)
def result = true Question.withTransaction status -> if(!question.validate()) result = false if(question.type!= 'textarea' && question.type!= 'textfield') if(!createoptionlist(optionlist, question, options)) question.errors.reject("question.option.validation.error") result = false if(optionlist == []) question.errors.reject("question.missing.options.error") /* If we're updating and the field type changes all options must be deleted. * Since we're inserting all options from scratch anyway, delete all options here. */ if(!insert) Question.executeUpdate("delete Option where question = :question", [question:question]) if(result) if(insert) question.position = updatepositions(question.form, question.position, insert) /* Question will only fail at critical errors at this point * since result already indicate whether validation succeded. * So if we encounter anything we need to throw an exception to abort the transaction. */ if(!question.save(flush:true)) throw new GrailsQueryException() saveoptions(optionlist, question) return result Illustrasjon : Eksempel på dokumentasjons- og kodestandard i praksis: 7
Vedlegg Product Backlog # Subject Assigned to Target version Admin lager nytt skjema Elizabeth Eier legger til felt i Elizabeth skjema 4 Eier legger til et valg i et spørsmål Elizabeth En ny bruker opprettes Terje Eier viser skjema 7 bruker gjennomfører spørreundersøkelsen 8 Bruker ser utfallet av egne svar 9 Eier ser utfallet av alles Elizabeth svar 4 0 Bruker gjenopptar Terje halvferdig besvarelse Bruker ser alle Terje undersøkelser som kan besvares Eier henter rapport som Elizabeth oppsummerer en enkel 4 undersøkelse Bruker logger på Terje 4 Layout for viewene. Terje Bruker lager spesialtilpasset rapport til en gitt rapport Eier knytter bilde til skjema Description Hvem det gjelder for består av en rekke spørsmål kan ha forskjellige typer svar: radio, check, dropdown, textfelt/area, epost, opplasting av fil?! kan ha forskjellige typer svar: radio, check, dropdown, textfelt/area, epost, opplasting av fil?! Kan være ved selvregistrering, ved admin, eller automatisk generert med løpenummer ved gjennomføring av spørreundersøkelse med alle spørsmål og svaralternativer åpner skjema, ser ett og ett spørsmål og velger svar (evt hopper over spørsmål), og til slutt avslutter undersøkelsen (resultat blir lagret) Med en gang og/eller alle undersøkelser han har besvart som oppsummering og/eller enkeltvis Innlogget bruker skal kunne lagre før undersøkelsen er ferdig Med status om fullstendig besvart eller ikke Alle spørsmål, svaralternativer med antall, prosentfordeling... Med ulike rettigheter. Sikker. Med språkvalg? Eller er dette valgt kun ved opprettelse av bruker? Layout for UI-et rundt viewene som skal brukes når scaffolding er slått av. Det presenteres en liste over spørsmål, med valg av type oppsummering (gjennomsnitt, sum, høyfrekvente ord i tekstbesvarelser o.l.) Bilde knyttes til hele skjema som enhet 8
# Subject Assigned Target Description to version 7 Eier knytter bilde til spørsmål Bilde kan være utgangspunkt for spørsmål 8 Tilfeldige spørsmål Terje Ut fra en gruppe med spørsmål kan systemet velge ut tilfeldige spørsmål, og/eller presentere spørsmål i tilfeldig rekkefølge. 9 Eier knytter bilde til svar Som hele svar eller illustrasjon til svar 0 Eier bestemmer rekkefølge på spørsmål i forhold til hverandre Dvs at svar på et spørsmål resulterer i endring i flyt mellom spørsmål Fikse testsystem Terje Vi trenger bedre tilbakemelding fra testene - de virker ikke noe særlig foreløpig Permanent database Terje passord osv etableres autodeploy til Tomcat script som kjører hver kveld under utviklingsperioden - eller oftere hvis vi vil 4 Teste flere servere Glassfish, Jboss, jetty, Tomcat/Apache Eier masseregistrerer brukere Terje Istedenfor å måtte sitte og registrere hver for seg når man har lang liste 8 Resultater av tester på epost Brukeren blir tilsendt resultatet av testen på mail. 9 Systemeier håndterer bedrifter som skal bruke systemet bedrifter 0 Søk på skjema Både for skjemaeier, og bruker 4 Skjematemplate funksjoner for utseende Spørsmålstype med checkbox som alternativ ved opprettelse av spørsmål, og funksjonalitet i Spørsmålstype med select Terje 4 Spørsmålstype med tekstfelt/tekstområde Bruker eller eier laster opp fil Fikse logging fra kontrollere og test. Terje besvarelse som alternativ ved opprettelse av spørsmål, og funksjonalitet i besvarelse som alternativ ved opprettelse av spørsmål, og funksjonalitet i besvarelse som svar eller som spørsmål Få logging til å virke. Lage en fungerende konfigurasjon. 9
# Subject Assigned to 7 Initialisering av sorteringsfeltet for spørsmål 8 Initialisering av sorteringsfeltet for alternativer 9 Bedre datofunksjon for skjemaer. 40 svartype for spørsmål gjøres om til valgfelt 4 Lag et brukervennlig UI for å lage nye spørreundersøkelser 4 Bedre resultatvisningen til survey 4 Løs problemet med ugyldig flowexecutionkey 44 Bind spørreskjemaene opp til en session. Elizabeth Terje Terje Target version 4 4 Forskjellige skjemautfall Elizabeth 4 Poengsum på skjemavalg Elizabeth 47 Hindre at brukeren kan gå tilbake og svare på spørsmål på nytt 48 Skrive om surveycontroller fra flow til normal kontroller Description Initialisering av sorteringsfeltet for spørsmål. Initialisering av sorteringsfeltet for alternativer Dato i nåværende tilstand lar seg ikke sammenligne. Den er for nøyaktig. istedenfor tekstfelt Akkurat nå er det vanskelig å navigere rundt i UI-et til skjemageneratoren. Skjemaene er inkonsistente. Det mangler validering. Redirect etter å ha f.eks. lagt til et spørsmål er ikke logisk(går til question/show istedet for til form/show). Nå er det ikke en brukervennlig som blir vist når brukeren er ferdig med å svare på spørsmålene. Les tittel. Sånn som det er nå kan alle fortsette alle på undersøkelser. Dette må bindes til en session. Et svar på en undersøkelse kan føre til flere utfall. Dette er nyttig hvis du for eksempel lager en test der forskjellige poengsummer gir forskjellige utfall. Et valg kan gi en poengsum som igjen summeres når skjemaet er ferdig fylt ut. Dette kan føre til forskjellige utfall og brukes til f.eks. tester. Det er nå mulig å bruke tilbakeknappen og svare på spørsmål på nytt(fører til GrailQueryException). Dette må hindres f.eks. ved å slå av cache. Vi skal ikke bruke flow. Logikken må også inn i service. 0
# Subject Assigned to 49 Flytting av skjemaer mellom grupper 0 endring av dato, evt andre felt på Form uten å slette besvarelser Target version Description I tilfelle en bruker er så uheldig at hun oppretter skjemaet i feil gruppe, så burde det være mulig å flytte det til en annen gruppe. Implementert som en select-boks i form/edit. Det bør kunne endres sluttdato på en pågående undersøkelse uten at avgitte svar slettes. Bør vel også kunne redigere f.eks. navn på avsluttede undersøkelser hvis navnet skal brukes om igjen på en ny versjon av undersøkelsen.