Functioneel ontwerp
- Grenzen van het project
- 1. Domain model
- 2. Actoren
- 3. Use case Diagram
- 4. User story's
- 5. Niet-functionele requirements
De casus is terug te vinden in het Plan van Aanpak.
Grenzen van het project
Zoals bekend uit het PvA gaat deze documentatie over slechts een deel van het gehele Project Management Portal. Het gaat hier specifiek over het onderdeel dat te maken heeft met de vertalingen. Voor de front-end geldt dat alles onder de "vertalingen" pagina binnen de grenzen van dit project valt, met toevoeging van de koppeling tab op de instellingen pagina. Voor de back-end geldt dat alles van de ProjectTranslations, ProjectTranslationStatistics en onderdelen van de ProjectSettings en het Project zelf betrekking hebben tot het project. Alles van het versiebeheersysteem, de vertalingstool, de vertaling bestandstypes en de CDN service horen hier ook bij. De toevoeging van Hangfire is door dit project gekomen, maar is niet gelimiteerd voor alleen de vertalingen functionaliteiten. Alles wat verder niet genoemd is valt buiten de grenzen van dit project.
1. Domain model
Dit domein model is uitgewerkt, omdat het een overzicht geeft van de onderdelen die een rol spelen in het systeem, en hoe deze onderdelen aan elkaar verbonden staan. Voor de uitwerking van de user story's en use cases is het belangrijk om te weten welke onderdelen er zijn en hoe deze met elkaar in verbinding staan.
Toelichting
Het is belangrijk om te weten dat het domeinmodel geen directe representatie is van het eindproduct, het domeinmodel is gebruikt ter inspiratie van de REST API voor het eindproduct. Verder heeft het domeinmodel geholpen bij het ontwerpen van de database en de structuur van de back-end. Dit is dus ook geen daadwerkelijke representatie van de database, of de REST API. Die zijn allen terug te vinden in het technisch ontwerp.
2. Actoren
Actoren zijn de personen of systemen die betrokken zijn bij het systeem en die een rol spelen bij het gebruik of de ontwikkeling ervan. Actoren kunnen zowel intern als extern zijn.
- Gebruiker
- Admin
- AI tool
- Versiebeheer systeem
2.1. ACT1: Gebruiker
De gebruiker binnen het systeem. De gebruiker kan de vertalingen van zijn project bekijken, bewerken en de vertalingen genereren in een nieuwe taal. Verder kan een gebruiker zijn vertalingen publiceren, zodat deze gebruikt kunnen worden op de productie omgeving. Een gebruiker kan ook gegevens zoals kosten, aantal vertalingen, gebruikte talen en vertalingsbestanden van zijn project inzien.
Een gebruiker classificeert meerdere types van gebruikers, zoals een project administrator, een klant of een interne medewerker bij Bluenotion. Deze classificatie is niet relevant voor dit project, maar wel voor de uitwerking van het portaal waar een andere afstudeerder aan werkt, en waar dit project onderdeel van is.
2.2. ACT2: Admin
De admin van het systeem. De admin kan alle acties uitvoeren die een normale gebruiker ook uit kan voeren, met toevoeging van de koppeling tussen een project en een versiebeheer systeem repository leggen. Deze actor moet niet verward worden met een project administrator, die alleen admin rechten heeft binnen één project. Deze is verder ook niet relevant voor dit project, maar wel voor de uitwerking het portaal waar een andere afstudeerder aan werkt, en waar dit project onderdeel van is.
2.3. ACT3: AI tool
De AI tool is verantwoordelijk voor het vertalen van de teksten. De AI tool is een externe tool die wordt gebruikt om de vertalingen te maken.
2.4. ACT4: Git versiebeheer systeem
Het Git versiebeheer systeem (Git) is een extern systeem dat verantwoordelijk is voor het beheren van de vertalingsbestanden en het publiceren van de vertalingen. Het Git versiebeheer systeem wordt gebruikt om de vertalingsbestanden op te slaan.
2.5 ACT5: CDN Service
De CDN Service is een externe service die verantwoordelijk is voor het hosten van de vertalingsbestanden. De CDN Service wordt gebruikt om de nieuwe vertalingsbestanden te hosten en te distribueren naar de eindgebruikers.
3. Use case Diagram
Dit use case diagram is uitgewerkt, om een overzicht te krijgen van de acties die de verschillende actoren uit kunnen voeren en welke secondaire actors hierbij betrokken worden. De tabel hieronder biedt hier ook inzicht in, maar het diagram geeft een gemakkelijker visueel overzicht.
4. User story's
In de volgende tabel zijn alle user story's uitgewerkt, inclusief de MoSCoW prioritering en de gerelateerde use cases. Verder staat er ook per user story of deze gerealiseerd is of niet. Zo is er een duidelijk overzicht van de user story's die gerealiseerd zijn en welke nog gerealiseerd moeten worden. Als een use case een link bevat is deze uitgewerkt of wordt daar op dat moment aan gewerkt. Een use case kan afgerond zijn zonder dat alle user story's gerealiseerd zijn, dit geldt niet voor de must have user story's. Deze moeten altijd gerealiseerd zijn voordat de gerelateerd use case als af gezien kan worden.
| User Story # | Gerelateerde Actors | Beschrijving | Prioriteit (MoSCoW) | Use case(s) | Gerealiseerd |
|---|---|---|---|---|---|
| FR1 | ACT2: Admin ACT4: Git versiebeheer systeem |
Als admin wil ik een project kunnen koppelen aan een Git repository, zodat de gebruiker de vertalingen van zijn project kan beheren. | Must have | UC1 | |
| FR2 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik een lijst van alle namespaces in mijn project kunnen zien. Zodat ik kan selecteren welke namespace ik wil beheren. | Must have | UC2, UC3 | |
| FR3 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik een namespace uit de lijst van opgehaalde namespaces kunnen selecteren, zodat ik de vertalingen binnen de namespace kan beheren. | Must have | UC2, UC3 | |
| FR4 | ACT1: Gebruiker | Als gebruiker wil ik een lege lijst van vertalingen aan kunnen maken in mijn taal naar keuze, zodat ik zelf vertalingen in kan vullen voor de gekozen taal. | Must have | UC3 | |
| FR5 | ACT1: Gebruiker | Als gebruiker wil ik een vertaling handmatig in kunnen vullen, zodat ik zelf controle heb over de vertalingen. | Must have | UC3 | |
| FR6 | ACT1: Gebruiker ACT3: AI tool ACT5: CDN Service |
Als gebruiker wil ik een selectie van een of meerdere vertalingen kunnen genereren aan de hand van de AI tool. Zodat ik meer controle heb over welke vertalingen ik handmatig in wil vullen en welke vertalingen ik wil laten genereren. | Must have | UC3 | |
| FR7 | ACT1: Gebruiker ACT3: AI tool |
Als gebruiker wil ik een lijst van ondersteunde talen van de AI tool te zien krijgen. Zodat ik weet in welke talen ik de mogelijkheid heb om de AI tool in te zetten. | Must have | UC2 | |
| FR8 | ACT1: Gebruiker ACT3: AI tool ACT5: CDN Service |
Als gebruiker wil ik alle vertalingen binnen mijn project kunnen genereren in een nieuwe ondersteunde taal van de AI tool, zodat ik tijd kan besparen met zelf vertalingen uitschrijven of door iemand anders uit laten schrijven. | Must have | UC2 | |
| FR9 | ACT1: Gebruiker | Als gebruiker wil ik een vertaling kunnen bewerken, zodat ik fouten kan corrigeren. | Must have | UC3 | |
| FR10 | ACT1: Gebruiker | Als gebruiker wil ik een maandelijks overzicht van mijn gemaakte kosten door gebruik van de AI vertalingen kunnen inzien, zodat ik een inzicht in de kosten voor mijn vertalingen krijg. | Must have | UC2, UC3 | |
| FR11 | ACT1: Gebruiker | Als gebruiker wil ik gemakkelijk kunnen zien welke vertalingen nog niet ingevuld zijn, zodat ik deze vertalingen in kan vullen of kan genereren. | Must have | UC3 | |
| FR12 | ACT1: Gebruiker ACT4: Git versiebeheer systeem ACT5: CDN Service |
Als gebruiker wil ik de vertalingen van mijn project kunnen publiceren, zodat de vertalingen gebruikt kunnen worden op de productie omgeving. | Must have | UC3 | |
| FR13 | ACT1: Gebruiker | Als gebruiker wil ik bij het genereren van een vertalingen in een nieuwe ondersteunde een melding krijgen als het aantal tokens hoger is dan het vastgestelde aantal, zodat ik weet dat er extra kosten aan verbonden zijn. | Must have | UC2 | |
| FR14 | ACT2: Admin ACT5: CDN Service |
Als admin wil ik een CDN service storage zone kunnen koppelen aan een project, zodat vertalingen op de CDN gepubliceerd kunnen worden, en de eindgebruikers de nieuwste vertalingen direct kunnen gebruiken. | Must have | UC1 | |
| FR15 | ACT2: Admin | Als admin wil ik de koppeling tussen een project en een versiebeheer systeem repository kunnen verwijderen, zodat ik de gebruiker kan ontkoppelen van het versiebeheer systeem. | Should have | UC1 | |
| FR16 | ACT1: Gebruiker | Als gebruiker wil ik vertalingen kunnen filteren op vertaalde en onvertaalde vertalingen, zodat ik snel kan zien welke vertalingen nog vertaald moeten worden. | Should have | UC3 | |
| FR17 | ACT1: Gebruiker | Als gebruiker wil ik vertalingen van een project kunnen filteren op taal, zodat ik alleen de gewenste vertalingen zie. | Could have | UC2, UC3 | |
| FR18 | ACT1: Gebruiker | Als gebruiker wil ik kunnen zien welke placeholders in een vertaling missen. Zodat ik deze gemakkelijk kan toevoegen, en mijn vertalingen kloppen. | Could have | UC3 | |
| FR19 | ACT1: Gebruiker | Als gebruiker wil ik kunnen zien welke vertaling(en) in een verkeerde taal vertaald zijn. Zodat ik deze aan kan passen. | Could have | UC3 | |
| FR20 | ACT2: Admin | Als admin wil ik bestandslocaties voor vertalingsbestanden kunnen instellen, zodat ik voor ieder project kan instellen waar er gezocht wordt naar vertalingsbestanden. | Won't have | - | - |
| FR21 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik een beschrijving aan een vertaling kunnen meegeven, zodat ik accuratere vertalingen krijg. | Won't have | - | - |
| FR22 | ACT2: Admin ACT4: Git versiebeheer systeem |
Als admin wil ik taal kunnen verwijderen, zodat ik alleen relevante vertalingen hoef te beheren. | Won't have | - | - |
| FR23 | ACT1: Gebruiker ACT3: AI tool |
Als gebruiker wil ik bij het genereren van één vertaling die meerdere betekenissen kan hebben een lijst van suggesties te zien krijgen, zodat ik zelf kan kiezen welke suggestie het beste bij de context van de vertaling past. | Won't have | - | - |
| FR24 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik een verwijderde taal kunnen herstellen, zodat ik deze niet opnieuw hoef in te vullen. | Won't have | - | - |
| FR25 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik één vertaling uit een namespace binnen mijn project kunnen verwijderen, zodat ik geen onnodige vertalingen in mijn project krijg. | Won't have | - | - |
| FR26 | ACT1: Gebruiker ACT4: Git versiebeheer systeem |
Als gebruiker wil ik een nieuwe vertaling binnen een namespace aan kunnen maken, zodat mijn vertalingen up to date blijven. | Won't have | - | - |
| FR27 | ACT1: Gebruiker | Als gebruiker wil ik een namespace van vertalingen in mijn project kunnen downloaden, zodat ik deze bij andere projecten kan gebruiken. | Won't have | - | - |
| FR28 | ACT1: Gebruiker | Als gebruiker wil ik een namespace met vertalingen in mijn project kunnen uploaden, zodat ik dezelfde vertalingen van andere projecten kan gebruiken. | Won't have | - | - |
4.1. Verschil user story en use case
In het geval van dit project is een user story een actie die een gebruiker kan uitvoeren in het systeem. Één user story kan resulteren in één use case, maar dit hoeft niet altijd het geval te zijn. Een use case kan meerdere user story's bevatten. Een use case is een volledige beschrijving van een actie die een gebruiker kan uitvoeren in het systeem.
4.2. Wanneer wordt een use case fully dressed uitgewerkt?
In het geval van dit project wordt een use case fully dressed uitgewerkt wanneer het een complexe actie betreft.
4.3. Wanneer is een use case uitgewerkt?
In dit document is te zien of een use case uitgewerkt is, als er een link is naar de use case in de kolom "Use case(s)" van de User Story.
4.4. Definitie MoSCoW
- Must have: Dit zijn de eisen die absoluut noodzakelijk zijn voor het project. Als deze eisen niet worden geïmplementeerd, dan is het project niet succesvol.
- Should have: Dit zijn de eisen die belangrijk zijn, maar niet noodzakelijk voor het project. Deze eisen kunnen worden uitgesteld naar een volgende release.
- Could have: Dit zijn de eisen die leuk zijn om te hebben, maar niet noodzakelijk zijn voor het project. Deze eisen kunnen worden uitgesteld naar een volgende release.
- Won't have: Dit zijn de eisen die niet worden geïmplementeerd in het project. Deze eisen kunnen worden uitgesteld naar een volgende release.
5. Niet-functionele requirements
| Niet-functionele requirement | Hoofd requirement | Sub requirement | Beschrijving | Impact |
|---|---|---|---|---|
| NFR1 | Usability | |||
| NFR1.1 | Gemak gebruik user interface | De user interface moet eenvoudig en intuïtief zijn voor de gebruiker. | Een gemakkelijke gebruikersinterface was belangrijk voor de gebruikers, omdat het vertaalproces lastig is. Ik heb de gebruikersinterface besproken en samen ontwerpen met een UX/UI Designer om hier aan te voldoen. | |
| NFR1.2 | Responsiviteit user interface | De user interface moet snel en responsief zijn, zodat de gebruiker snel kan werken. Verder moet de user interface fatsoenlijk schalen op desktops en laptops. | Een responsive web applicatie, grotendeels van de applicatie was al responsive. Op de nieuwe plekken waar dit niet zo was heb ik dit toegepast. | |
| NFR1.3 | Vertaalproces feedback | De gebruiker moet live feedback krijgen over het vertaalproces. | De impact van de live feedback is niet super groot, in het product wordt er feedback geleverd door een animatie te tonen die het duidelijke maakt dat het vertaalproces bezig is. | |
| NFR1.4 | Over the air updates | De eindgebruikers die de applicatie gebruiken moeten in staat zijn om de nieuwe vertalingen te zien, nadat de gebruiker in het portaal de vertalingen heeft gepubliceerd. | Deze niet functionele eis had een zeer grote impact op het uiteindelijke product, er is veel tijd in het product gestopt om aan de eis te voldoen. Dit is gedaan met een CDN. Zie de volledige toelichting hier. | |
| NFR2 | Reliability | |||
| NFR2.1 | Nauwkeurigheid vertalingen | De vertalingen moeten nauwkeurig zijn en geen fouten bevatten. | De impact van deze eis was erg belangrijk voor het eindproduct. De kwaliteit van de vertalingen heeft impact op alle projecten die het zal gaan gebruiken. Ik heb hiervoor onderzoek gedaan naar de meest passende AI vertaling tools waarin ik ook onderzoek doen naar de kwaliteit van de vertalingen. Bekijk het volledige onderzoek | |
| NFR2.2 | Foutafhandeling | Het systeem moet fouten kunnen afhandelen en de gebruiker hierover informeren op een gebruikersvriendelijke manier. | Goede foutafhandeling voor dit product bouwen was lastig, omdat er veel verschillende systemen gekoppeld zijn. Sommige foutmeldingen horen niet zichtbaar te worden voor de gebruiker, omdat het bijvoorbeeld met een systeeminstelling te maken heeft. Voor alle interne fouten die afgehandeld worden zijn vertalingen aangemaakt. Zo kunnen alle interne fouten voor alle gebruikers duidelijk gemaakt worden. De interne fouten gaan vooral over fouten die de gebruiker maakt, zoals verkeerde id's, missende velden, niet toegestane acties en andere validaties. | |
| NFR2.3 | Betrouwbaarheid vertaalproces | In 90% van de gevallen moeten het genereren van vertalingen in een ondersteunde taal, volgens de happy flow slagen. | De impact van deze niet functionele eis is belangrijk, maar lastig om goed te meten en om eraan te voldoen. Dit komt onder andere door de verschillende systemen die betrokken zijn bij het proces. Ik heb het eindproduct tijdens het ontwikkelen en na afronding van nieuwe functionaliteiten getest op de testomgeving, waarna het vertalingsproces in vrijwel alle situaties goed ging. | |
| NFR3 | Performance | |||
| NFR3.1 | Snelheid vertaalproces | Het vertaalproces van een heel project moet binnen één minuut worden voltooid, Voor losse vertalingen mag het slechts enkele seconden duren. | De impact van de snelheid van het vertalingsproces is groot, omdat als het vertalingsproces erg lang duurt het gebruikers afweert om de tool te gebruiken. Echter heeft de grootte van het project ook veel impact op de duratie van het vertalen. Voor de template (10-15k karakters over het gehele project) geldt dat het aanpassen of genereren van een selectie van vertalingen slechts enkele seconden duurt. Het hele project vertalen duurt ongeveer 20-30 seconden. Op plekken waar er ruimte voor was heb ik het proces zoveel mogelijk geoptimaliseerd zoals het parallelliseren van het genereren van de vertalingen en het ophalen van de vertalingen. | |
| NFR3.2 | Schaalbaarheid | Het systeem moet schaalbaar zijn en in staat zijn om grote hoeveelheden vertalingen te verwerken. | De impact van deze niet functionele eis is niet super groot, het aantal projecten dat beheerd zal worden in het portaal zou niet voor een schaling probleem moeten zorgen. Ik heb geen bewuste stappen genomen om hieraan te voldoen, omdat de technieken die gebruikt worden ervoor zorgen dat deze eis out of the box gedekt wordt. Verder is de hosting ervoor verantwoordelijk om het aantal netwerkverkeer af te handelen. | |
| NFR3.3 | Throughput en reactie tijd | De service die de vertalingen aanbied nadat deze gepubliceerd zijn moet 10.000 RPS (Requests Per Second) kunnen afhandelen. Verder moeten de vertalingsbestanden binnen 200 milliseconden beschikbaar zijn. | De impact van deze eis is groot, omdat eindgebruikers niet lang willen wachten op een pagina/website. Als vertalingen te lang duren met laden is er een mogelijkheid dat ze gefrustreerd raken met het systeem. Om aan deze eis te voldoen heb ik een CDN gebruikt, deze staan bekend om hun snelle reactietijden en ondersteuning voor hoge data load. Zie de volledige toelichting hier. | |
| NFR4 | Supportability | |||
| NFR4.1 | Ondersteuning voor vertaling placeholders | Het systeem moet om kunnen gaan met placeholders in vertalingen. bijv. "Hallo,{naam}" |
De impact van deze eis is erg groot, als placeholders mee vertaald worden werken deze niet juist en worden deze ook niet ingevuld. Waardoor de eindapplicatie mogelijk onverwacht gedrag gaat vertonen of gebruikers in verwarring brengt. Om dit te voorkomen bereidt ik de vertalingen voor, voordat deze vertaald worden en na het vertalen wordt dit proces andersom herhaalt. Dit zorgt ervoor dat de placeholders intact blijven gedurende het vertalingsproces. | |
| NFR4.2 | Flexibiliteit versiebeheer systeem | Het systeem moet andere version control systemen ondersteunen. | De impact van de ondersteuning van meerdere versiebeheersystemen was klein op de MVP. Maar nadat de MVP was afgerond en er ruimte was voor extra functionaliteit werd duidelijk hoe belangrijk deze flexibiliteit was. De exacte stappen over de abstractie zijn hier terug te vinden. | |
| NFR4.3 | Ondersteuning meerdere bestandsformaten | Het systeem moet in staat zijn om meerdere bestandsformaten te ondersteunen. | De impact van het ondersteunen van meerdere bestandsformaten is groot. Het was bekend dat na de MVP mogelijk andere bestandsformaten ondersteund zouden moeten worden. In de looptijd van mijn project bleek dit ook relevant te zijn omdat een ander bestandstype gewenst was om ondersteund te worden. Bekijk de volledige toelichting en werking hier | |
| NFR4.4 | Ondersteuning flexibiliteit vertalingstool | Het systeem moet in staat zijn om in de toekomst andere vertalingstools te ondersteunen | De impact van de flexibiliteit voor een andere vertalingstool is erg belangrijk. Als er in de toekomst een AI tool uitkomt die veel beter blijkt te zijn in vertalen, wat zeker mogelijk is, moet het mogelijk zijn om deze tool ook te kunnen gebruiken. Om dit mogelijk te maken heb ik een abstractielaag voor de vertalingstool toegepast. Bekijk de volledige toelichting en werking hier | |
| NFR4.5 | Ondersteuning meerdere talen | Het systeem moet in staat zijn om meerdere talen te ondersteunen. | De impact van de ondersteuning van verschillende talen op zich is niet heel groot. Het is echter wel lastig om dit achteraf toe te voegen, als hier geen rekening mee gehouden is. In mijn geval gebruikte het project voor het portaal i18next en .NET's localization, inclusief string localizers om vertalingen aan te bieden, en dus ook andere talen te ondersteunen. |