Project Fasering Documentatie Gebaseerd op het KD Applicatie- en mediaontwikkeling augustus 2014 Auteur: Jim Dunk Datum: 01 augustus 2015 Project Fasering Documentatie Inleiding Algemeen Planning en logboek Kerntaak 1: Ontwerpen van de applicatie, (cross)media-uiting 1.1 Stelt de vraag en/of informatiebehoefte vast 1.2 Maakt een plan van aanpak 1.3 Levert een bijdrage aan een functioneel ontwerp of Game Design Document 1.4 Maakt een technisch ontwerp 1.5 Richt de ontwikkelomgeving in Kerntaak 2: Realiseren van de applicatie, (cross)media-uiting 2.1 Legt een gegevensverzameling aan 2.3 Realiseert een (cross)media uiting en/of systeem 2.5 Test het ontwikkelde product 2.6 Optimaliseert de game of (cross)media-uiting 2.7 Bewaakt de voortgang en evalueert het project Kerntaak 3: Implementeren van de applicatie of (cross)media-uiting 3.1 Maakt of levert een bijdrage aan het implementatieplan 3.3 Implementeert een applicatie of (cross)media-uiting en/of -systeem 3.4 Evalueert een implementatie Kerntaak 4: Onderhouden en beheren van de applicatie, (cross)media-uiting 4.1 Onderhoudt applicaties of (cross)media-uiting 4.2 Verzamelt, controleert, bewerkt en archiveert (cross)mediabestanden 4.3 Bewaakt de samenhang van media-uitingen 4.4 Stelt script samen ten behoeve van het samenvoegen van content 4.5 Beheert de content Beoordeling communicatie Beoordeling documentatie Standaarden coderen Codeblokken Operatoren Ma MIG, Jim Dunk Pagina 1 van 16
Commentaar Ma MIG, Jim Dunk Pagina 2 van 16
Inleiding In dit document vind je informatie over de fases en voor het maken van documentatie bij het uitvoeren van projecten als Mediadeveloper. Algemeen De volgende opmerkingen gelden voor elk document dat je schrijft binnen de uitvoering van een project. Controleer dus elke document voor dat je inlevert of laat controleren op deze punten: Begin elk document met een duidelijke inleiding. In de inleiding vertel je waar het document over gaat zodat de lezer weet wat hij gaat lezen. Probeer daarbij zo specifiek mogelijk te zijn; geef geen uitleg wat een definitiestudie, FO of TO is maar leg kort uit wat je gaat vertellen, hoe het document is op gebouwd of iets dat de lezer moet weten voordat hij het document gaat lezen. Zorg dat de opmaak van de documenten consequent is. Gebruik niet onnodig veel verschillende soorten opmaak van de tekst zonder dat je daar een reden voor hebt, dit leidt alleen maar af van de inhoud. Gebruik zoveel mogelijk de functies van je teksteditor om het document netjes op te maken, bijvoorbeeld kop- en voetteksten, automatische inhoudsopgave, opmaakprofielen etc. De verschillende documenten binnen een project moeten een gelijke opmaak hebben zodat je duidelijk kunt zien dat ze bij elkaar horen. Zorg dat belangrijke informatie duidelijk in of op het document vermeld staat. Als je een document op de grond vindt moet je kunnen zien van wie het is, waarvoor en wanneer het is geschreven en welke pagina. Geef alle documenten een duidelijk versienummer zodat je weet wat je laatste versie is, en wat een eerdere versie is.. Elke keer als je een document (voorlopig) oplevert geef het een nieuw nummer. Aan het nummer moet ook te zien zijn dat het een definitieve versie is. Begin je nummering bijvoorbeeld met 0.1, 0.2, 0.3... De definitieve versie krijgt dan het nummer 1.0. Als het definitieve document in de loop van het project toch nog moet aanpassen, door bijvoorbeeld nieuwe informatie of inzichten, ga je verder met 1.1, 1.2 etc. Zo is duidelijk te zien dat de laatste documenten een aanpassing is op de definitieve versie. Planning en logboek Om het proces van het maken van een project of opdracht goed te laten verlopen is het handig om een planning te maken. Hierdoor kan je zien wanneer welk onderdeel af moet zijn, of er verschillende fasen zijn die je moet plannen en hoeveel tijd het project of de opdracht in beslag gaat nemen. Om tijdens een project of een opdracht, de werkzaamheden die je doet goed te volgen, zul je een logboek bij moeten houden. Het logboek verschaft de projectbegeleider inzicht in het verloop van je project (uitvoering), in de planning en in het realiseren van je product. Je werkzaamheden leg je vast om je voortgang te bewaken. Ma MIG, Jim Dunk Pagina 3 van 16
Lever bij elk product dat je oplevert je planning en je logboek als bijlage in. De planning en het logboek zijn documenten die de projectbegeleider van jou wil zien. Dit zijn dus geen documenten die de opdrachtgever wil zien. Ma MIG, Jim Dunk Pagina 4 van 16
Kerntaak 1: Ontwerpen van de applicatie, (cross)media-uiting De volgordelijke plaats van de documenten binnen het proces: Schriftelijk advies --------> Functioneel ontwerp --------> Technisch ontwerp -------------> Plan van aanpak -------------------------------------------------------------------------------------------------------> Bovenstaande betekent dat werkproces 1.2 parallel loopt aan de andere werkprocessen en van invloed is op alle te schrijven documenten binnen kerntaak 1. 1.1 Stelt de vraag en/of informatiebehoefte vast Input: Projectbeschrijving Output: Schriftelijk advies/offerte vervolgens opdrachtgever Voor wie: Opdrachtgever Schriftelijk advies/offerte: - Eisen en wensen opdrachtgever(moscow) - Haalbaarheid eisen en wensen - Voor- en nadelen afwegen en conclusie trekken - Uren- en kostenopgave, kosten alleen indien mogelijk - Grove planning op basis van ontwerp, realisatie, implementatie en onderhoud/beheer fase 1.2 Maakt een plan van aanpak Input: Schriftelijk advies,!! Feedback van de opdrachtgever Output: Plan van aanpak vervolgens opdrachtgever Voor wie: De opdrachtgever Plan van aanpak: - Projectomschrijving cq omgeving - Doelstelling - (Wat is het probleem?) - Doelgroep - Op te leveren producten en diensten - Alle werkzaamheden benoemen en koppelen aan projectlid (zie FO en TO) - Tijdpad uitzetten voor de werkzaamheden - Planning gedetailleerd - Communicatie(NAW, Tel, IM etc) gegevens van de projectleden (ook de opdrachtgever) Ma MIG, Jim Dunk Pagina 5 van 16
1.3 Levert een bijdrage aan een functioneel ontwerp of Game Design Document Input: Schriftelijk advies Output: Functioneel ontwerp vervolgens opdrachtgever Voor wie: Opdrachtgever Functioneel ontwerp: - Verwachtingen van de doelgroep - Concept - Hoe je de doelgroep benadert - Eisen en wensen van de opdrachtgever(moscow) verder uitgewerkt - Per functionaliteit of userstory een wireframe of klikbare prototype - Menustructuren en stroomdiagram - Blauwdruk acceptatie testplan voor functionele test uit te voeren in KT2 en KT3 * - Afhankelijkheden van andere systemen/bronnen(algemeen) 1.4 Maakt een technisch ontwerp Input: Schriftelijk advies, Functioneel ontwerp Output: Technisch ontwerp Voor wie: Team en nieuwe medewerkers Technisch ontwerp: - Database ontwerp / ERD / Type velden - Welke ontwikkelomgeving er gebruikt gaat worden - Toelichten van de gekozen oplossing(en) - Uitwerking van complexe functionaliteiten in wireframe - Afhankelijkheden van andere systemen/bronnen(specifiek) - Sequence diagram 1.5 Richt de ontwikkelomgeving in Input: Functioneel Ontwerp en Technisch Ontwerp Output: Korte beschrijving (mag ook in TO worden opgenomen) Voor wie: Team en nieuwe medewerkers Ma MIG, Jim Dunk Pagina 6 van 16
Beschrijving inrichting van ontwikkelomgeving: - Welke taal ga je gebruiken - Welke hulpmiddelen heb je nodig - Hoe pak je de inrichting aan Kerntaak 2: Realiseren van de applicatie, (cross)media-uiting 2.1 Legt een gegevensverzameling aan Input: Functioneel Ontwerp en Technisch Ontwerp Output: Digitaal met data Voor wie: Team Fysiek bewijs in digitaal formaat: - Database aanmaken - Back up/dump van database - Database moet gevuld zijn met voorbeeld data 2.3 Realiseert een (cross)media uiting en/of systeem Input: Technisch ontwerp Output: Digitaal formaat met data of screenshots van het systeem en een realisatieverslag Fysiek bewijs in digitaal formaat: - Gehele back up van project - Moet gevuld zijn met voorbeelddata - Opgenomen in versiebeheer - Screenshots van het systeem (applicatie en database) - Conventie en documentatie Realisatieverslag: - Persoonlijke logboek in verhaalvorm - Wat ging goed of fout -> noem voorbeelden 2.5 Test het ontwikkelde product Input: Technisch ontwerp Output: Systeemtestrapport Ma MIG, Jim Dunk Pagina 7 van 16
Sjabloon Systeemtestrapport: - Beschrijving van wat je gaat testen (testplan) - Overzicht van testers en hun inzet - Screenshots van het testen (eventuele foutmeldingen) - Beschrijving van de uitgevoerde verbeteringen 2.6 Optimaliseert de game of (cross)media-uiting Input: Systeemtestrapport Output: Optimalisatieplan vervolgens opdrachtgever Voor wie: Opdrachtgever en team Optimalisatieplan - Verzamelen testresultaten en verbeterpunten aangeven - Gebruiksvriendelijkheid rapport - Toegankelijkheid rapport - Overzicht zoekmachine instellingen 2.7 Bewaakt de voortgang en evalueert het project Input: Plan van aanpak en teamvergaderingen Output: Planning Voor wie: Opdrachtgever en team Planning (uitgebreide) - Teamleden - Tijdindeling - Meetpunten Ma MIG, Jim Dunk Pagina 8 van 16
Kerntaak 3: Implementeren van de applicatie of (cross)media-uiting 3.1 Maakt of levert een bijdrage aan het implementatieplan Input: De gerealiseerde applicatie Output: Implementatieplan en presentatie en opdrachtgever Voor wie: Systeem- en/of Applicatiebeheerder van de live hosting omgeving Implementatieplan: - Beschrijving van de veranderingen in de organisatie - Beschrijving hoe en wie de gegevens gaan converteren, importeren of invoeren - Ingebruikname: big bang, gefaseerd, parallel, gecombineerd? - Tijdpad/draaiboek - Beschrijving van alle te installeren hard- en software - Infrastructuur, (Web, DB, Mail.)Servers en modules - Trainingsplan - Procedures en verantwoordelijkheden - Beschrijving van toekomstig applicatie-, gegevens- en technisch beheer Presentatie van het implementatieplan aan projectbegeleider, opdrachtgever en betrokken medewerkers. Een hand-out printen voor in de portfolio/bewijzenmap. 3.3 Implementeert een applicatie of (cross)media-uiting en/of -systeem Input: Implementatieplan Output: Implementatierapport Implementatierapport - Installeert volgens implementatieplan - Overdracht beheer - Vastleggen van uitvoer implementatieplan 3.4 Evalueert een implementatie Input: Implementatieplan en uitkomst van implementatie Output: Rapport met conclusies en verbeterpunten en procesverslag en opdrachtgever Ma MIG, Jim Dunk Pagina 9 van 16
Procesverslag van het gehele implementatietraject: - Hoe verliep de voorbereiding - Hoe verliep de uitvoering, denk aan: conversie, invoering, tijdpadbewaking, training, procedures hanteren, overdracht naar beheer Rapport met conclusies en verbeterpunten Ma MIG, Jim Dunk Pagina 10 van 16
Kerntaak 4: Onderhouden en beheren van de applicatie, (cross)media-uiting 4.1 Onderhoudt applicaties of (cross)media-uiting Input: Functioneel ontwerp Output: Onderhoud- en beheerplan, Rapport over de uitvoering van het onderhoud en opdrachtgever Voor wie: Systeem- en/of Applicatiebeheerders en toekomstige ontwikkelaars Onderhoud- en beheerplan: - Vastleggen verantwoordelijkheden per applicatie ( volgens SLA) - Procedures voor preventief onderhoud per applicatie(monitoring, Test sequences) - Procedures voor back-up en restore van applicatie(s) en data - Procedures voor virus bescherming van applicatie(s)en data - Registratieformulier voor incidenten per applicatie - Registratieformulier voor (nieuwe) eisen en wensen per applicatie Uitvoeren van procedures uit het onderhoud- en beheerplan - Uitvoeren preventief onderhoud en registreren/documenteren hiervan - Uitvoeren back-up en restore procedure en registreren/documenteren hiervan - Uitvoeren virus bescherming en registreren/documenteren hiervan - Registreren van één of meerdere incidenten en het bepalen van de vervolgactie - Registreren van één of meerdere wensen/eisen en het bepalen van de vervolgactie - Inventariseren wensen/eisen d.m.v. interviews gebruikers - Registreren in formulier - Bepalen vervolgactie - Kort verslag over genomen keuzes - Rapporteren van alle ondernomen stappen aan opdrachtgever/projectbegeleider 4.2 Verzamelt, controleert, bewerkt en archiveert (cross)mediabestanden Input: Alle projectdocumenten Output: Archiveringsplan en een daadwerkelijk archief (fysiek of digitaal) Archiveringsplan (procedures voor het archiveren van (gegevens van) applicaties) - Toelichting gewenste format, type, kwaliteit en compressiefactor van de mediabestanden - Analyse aangeleverde format, type, kwaliteit en compressiefactor van de mediabestanden - Conversie mediabestanden Ma MIG, Jim Dunk Pagina 11 van 16
Archief - Digitaal 4.3 Bewaakt de samenhang van media-uitingen Input: De gerealiseerde applicatie Output: Mediaplan en opdrachtgever Mediaplan - Audio en visuele stijl samenhang controle - Toelichting (sociale)media mogelijkheden 4.4 Stelt script samen ten behoeve van het samenvoegen van content Input: De gerealiseerde applicatie Output: Content template en opdrachtgever Content template - Layout keuze toelichting - Layout template 4.5 Beheert de content Input: Onderhoud- en beheerplan Output: Contentbeheerplan en een fysiek bewijs in digitaal formaat of screenshots van het systeem Contentbeheerplan: - Beschrijving van de route die content aflegt vanaf creatie tot publicatie - Beschrijving van verdeling van rollen, rechten en verantwoordelijkheden - Aan welke eisen moet de aangeleverde content voldoen? - Hoe wordt de content actueel gehouden? - Beschrijving van de wijze waarop content in de applicatie(s) wordt bewerkt en ingebracht, denk aan: Procedures (CMS, schermen, etc.), bewerking van analoog naar digitaal (scannen, converteren, etc.), Opsomming en beschrijving van gebruikte formaten. Fysiek bewijs in digitaal formaat: - De applicatie met gegevens - database moet gevuld zijn met representatieve data Screenshots van het systeem (applicatie en database) Ma MIG, Jim Dunk Pagina 12 van 16
Beoordeling communicatie Waar letten wij op! Beoordeling documentatie Tijdens het beoordelen van de documentatie wordt er op de volgende punten gelet. Titelblad: Inhoudsopgave: Voorwoord: Inleiding: Kern: een duidelijk voorblad met daarop vermeld: de titel van het document plaats, de maand en het jaartal van publicatie (inlever datum) de inhoudsopgave vermeldt de titels van de hoofdstukken, paragrafen met de daarmee corresponderende nummering en de pagina s. Deze moet automatisch worden gegenereerd met Word. De inhoudsopgave moet een duidelijk overzicht geven van het document. hierin behandel je zaken die niet rechtstreeks in verband staan met het onderwerp zoals: bedankjes aan medewerkers en instellingen de aanleiding tot het document als er een vorige document bestaat: het verband met het vorige een definitie en afbakening van het onderwerp: de probleemstelling (tip: gebruik hierbij de project naam) een uitleg over de opbouw van het document toelichting op de methode van onderzoek Opmerking: het voorwoord en de inleiding mogen op 1 pagina worden gezet. de antwoorden op alle vraagstukken en opdrachten Geef niet te veel maar zeker niet te weinig antwoord op vragen en opdrachten. Verwerk de vraag of opdracht in uw antwoord, vermeld anders de vraag of opdracht voorafgaand aan uw antwoord. Geef duidelijk aan om welke vragen opdrachten en/of hoofdstukken het gaat. In de inleiding heeft je voor een probleemstelling gekozen waardoor het document zich kan beperken tot een thema. De probleemstelling is de centrale vraag die beantwoord moet worden. De belangrijkste aspecten die je bij het schrijven in de gaten moet houden zijn: Ma MIG, Jim Dunk Pagina 13 van 16
de overzichtelijkheid: die moet blijken uit de indeling in hoofdstukken en paragrafen (Zie ook de inhoudsopgave) de objectiviteit: beperk je bij de weergave van de feiten tot die feiten. Loop niet op conclusies vooruit. Slot: Dit is het laatste hoofdstuk waarin: een terugblik op de kern wordt gegeven (samenvatting) conclusies uit de voorafgaande hoofdstukken worden getrokken een mening van de schrijver wordt geformuleerd. (o.a. Wat vond je ervan en wat heb je ervan geleerd) Bronvermelding: geef precies aan waar je de informatie gevonden hebt (boeken, tijdschriften, kranten, Internet). Bij internet vermeldt je de site naam. Opmerking: het slot en de bronvermelding mogen op 1 pagina worden gezet. De verzorging: Zorg dat je alle koppen en subkoppen een opmaakprofiel geeft. Dit heb je nodig om later uw inhoudsopgave te genereren. De hoofdstukken en paragrafen dienen exact dezelfde benaming te hebben als in de inhoudsopgave. (Gebruik hiervoor de optie Inhoudsopgave in Word) Gebruik een voettekst met daarin, (links)namen, (midden)documentnaam, (rechts)blz. nummering. nummer de pagina s behalve titelblad. De (hoofd)letters die jij voor de hoofdstuktitels enz. gebruikt moeten consequent van dezelfde soort zijn. Het standaard lettertype dat je gebruikt is Arial 11pt. De hoofdstukken dienen boven aan een volgende pagina te beginnen. Verwijzingen en/of voetnoten dienen steeds op dezelfde wijze te zijn aangegeven. Algemeen Wanneer je informatie van Internet haalt let dan op het volgende: letterlijk kopiëren van Internet is niet goed. Filter alle onnodige informatie er tussenuit en geef duidelijk antwoord op de vragen, niet meer en niet minder. Bewaar zelf altijd een digitale kopie van de instructie. Op deze manier heb je altijd een back-up van jouw document en kun je dit document later gebruiken als referentie materiaal. Standaarden coderen Er zijn een aantal redenen waarom de layout van de code van groot belang is. Met name zorgt een goede layout voor een verhoging van de kwaliteit van de code. In de code sluipt heel gemakkelijk een foutje. Bij een goede layout is het vaak al moeilijk een fout te vinden en te herstellen, laat staan bij code die onoverzichtelijk is opgesteld. De code moet later bij onderhoud van het programma met zo min mogelijk moeite gelezen kunnen worden. Onoverzichtelijk geschreven code maakt dit juist moeilijk zo niet onmogelijk. De code moet door anderen gelezen Ma MIG, Jim Dunk Pagina 14 van 16
kunnen worden. Als je samenwerkt met anderen, is het handig als die anderen ook de code kunnen lezen die jij geschreven hebt. Codeblokken Codeblokken zijn regels code die tussen accoladen staan. Binnen een codeblok kunnen weer andere codeblokken voorkomen. Zo staat in het voorbeeld hieronder de codeblok van een lus binnen de codeblok van een methode staan. Een codeblok wordt voorafgegaan door een openingsaccolade { en wordt afgesloten met een sluitaccolade }. Na een openingsaccolade springt je op de volgende regel één tab in. Na de sluitaccolade springt je op de volgende regel terug.. De openingsaccolade staat als laatste teken op een regel na een spatie meteen na bijvoorbeeld het sluithaakje na van een methode. De sluitaccolade staat als enig teken op de regel en in de kolom van de eerste letter die staat op de regel van de openingsaccolade. Voorbeeld: tekentekst($ tekst) { int teller; coderegel; coderegel; for( teller = 0; teller < 10; teller ++) { coderegel ; coderegel ; } coderegel ; coderegel ; } Operatoren Vergelijkingsoperatoren (==,!=, <, <=, > en >=) worden altijd omgeven door spaties. Voorbeelden: for( teller = 0; teller < 10; teller ++) Ook numerieke operatoren ( *, /, +, -, %, *=, /=, +=, -=, %=, ++, en --) worden omgeven door spaties, één ervoor en één erachter. Voorbeeld: som = a + b; In dit voorbeeld komt ook de toekenningsoperator ( =) voor die ook door spaties omgeven wordt. Commentaar Toelichting op je code is heel belangrijk. Zo kan de ander met wie je samenwerkt, de code begrijpen en kun je zelf de code een jaar later ook nog begrijpen. Ma MIG, Jim Dunk Pagina 15 van 16
Om op één regel commentaar te leveren gebruik je // en om op meerdere regels achter elkaar commentaar te zetten, gebruik je /* */. Zet in ieder geval boven elk blok PHP-code commentaar, boven elke klasse en elke methode in de klasse: In commentaar dat over de gehele klasse gaat, staat de naam van de klasse, een algemene beschrijving van de klasse, de naam van de auteur en het versienummer met de datum van de laatste wijziging. Boven elke methode staat de naam van de methode, een algemene beschrijving van de methode, de parameters en wat de teruggave is. Als er geen parameters zijn, dan staat er achter Parameters: geen. Hetzelfde geldt voor return. Ook wordt er eventueel naar andere methodes binnen (zoals in het voorbeeld) of buiten de klasse verwezen. Door deze manier van commentaar schrijven (zie de dubbele asteriksen aan het begin en het einde van het commentaar) kan er op eenvoudige manier een PHPdoc gemaakt worden. Voor een voorbeeld van een PHPdoc, zie: http://manual.phpdoc.org/htmlsmartyconverter/hands/phpdocumentor/tutorial_phpdocumen tor.howto.pkg.html#basics.docblock Zie verder voor de conventies van coderen: http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html Ma MIG, Jim Dunk Pagina 16 van 16