MA | Project documentatie 2016 v1.2
Gebaseerd op het KD Applicatie- en mediaontwikkeling
Algemeen
Planning en logboek
KT 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
KT 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
KT 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
KT 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
Commentaar
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 Schriftelijk Advies, 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. Vermijdt onnodig gebruik van ingewikkelde formuleringen als het document is bedoeld voor de opdrachtgever. 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.
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.
| Naam: | Groep: | Project: |
|---|---|---|
| Datum | Tijd | Activiteit |
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.
Werkproces 1.1 Stelt de vraag en/of informatiebehoefte vast
Doel: Verwachtingen afstemmen
Input: Projectbeschrijving/Briefing/RFP
Output: Schriftelijk advies/Offerte
Beoordeling: Projectbegeleider vervolgens opdrachtgever
Voor wie: Opdrachtgever
Schriftelijk advies/Offerte:
- Algemene aanleiding/inleiding/omschrijving van de gewenste werkzaamheden
- Bij een waterval proces, alle eisen en wensen van de opdrachtgever beschrijven en indelen op prioriteit volgens MoSCoW methode
- Bij een Agile proces, omzetten van alle eisen en wensen van de opdrachtgever naar userstories
- Haalbaarheid van cruciale eisen en wensen
- Voor- en nadelen beschrijven van cruciale eisen en wensen en adviseren
- Uren- en kostenopgave
- Grove planning op basis van ontwerp, realisatie, implementatie en onderhoud/beheer fase
Werkproces 1.2 Maakt een plan van aanpak
Doel: Vastleggen wat je gaat doen
Input: Schriftelijk advies, !! Feedback van de opdrachtgever
Output: Plan van aanpak
Beoordeling: Projectbegeleider vervolgens opdrachtgever
Voor wie: Opdrachtgever en team
Plan van aanpak:
- Projectomschrijving
- Aanleiding > Wat is ‘de uitdaging’ en waarom nu?
- Doelstelling > Wat wil de opdrachtgever bereiken en gericht op welke doelgroep?
- Op te leveren resultaten, producten en/of diensten
- Alle activiteiten benoemen en koppelen aan projectleden (zie FO en TO)
- Fasering en gedetailleerde activiteitenplanning
- Risico’s benoemen
- Taken, verantwoordelijkheden en contactgegevens van de projectleden
- Hoe ga je communiceren, onderling, maar ook met opdrachtgever; welke tools ga je daar evt voor gebruiken.(Elke week Skypen, per mail, etc.)
Werkproces 1.3 Levert een bijdrage aan een functioneel ontwerp of Game Design Document
Doel: Vastleggen hoe je het gaat doen vanuit de gebruikers
Input: Schriftelijk advies en PvA
Output: Functioneel ontwerp
Beoordeling: Projectbegeleider vervolgens opdrachtgever
Voor wie: Opdrachtgever en team
Functioneel ontwerp:
- Doelgroep/Eindgebruikers > Wie zijn ze?, wat verwachten ze, hoe benaderen we ze
- Eisen omzetten naar functionaliteiten/userstories
- Per functionaliteit/userstory een wireframe of klikbare prototype
- Sitemap/Menustructuur
- Stroomdiagram van een belangrijke functionaliteit/userstory
- Opzet van een acceptatietestplan uit te voeren in KT2
- Eenvoudige beschrijving van afhankelijkheden van andere systemen/bronnen/diensten/API’s/sites
Werkproces 1.4 Maakt een technisch ontwerp
Doel: Vastleggen hoe en waarom je het gaat doen vanuit de techniek
Input: Schriftelijk advies, Functioneel ontwerp
Output: Technisch ontwerp
Beoordeling: Projectbegeleider
Voor wie: Teamleden en nieuwe medewerkers
Technisch ontwerp:
- Per complexe functionaliteit/userstory een wireframe met gedetailleerde uitwerking
- Toelichten van de gekozen oplossing(en)
- Database ontwerp/model / Entity Relation Diagram / Type velden
- Sequence diagram van een complexe functionaliteit/userstory
- Volledige beschrijving van afhankelijkheden van andere systemen/bronnen/diensten/API’s/sites
Werkproces 1.5 Richt de ontwikkelomgeving in
Doel: Inzicht verkrijgen van OTAP omgevingen
Input: Functioneel Ontwerp en Technisch Ontwerp
Output: Resultaat opnemen in het technisch ontwerp
Beoordeling: Projectbegeleider
Voor wie: Teamleden en nieuwe medewerkers
Beschrijving inrichting van ontwikkelomgeving:
- Welke ontwikkelomgeving er gebruikt gaat worden
- Welke taal ga je gebruiken
- Welke hulpmiddelen heb je nodig
- Hoe pak je de inrichting aan en is het gelijk aan de productieomgeving
Kerntaak 2: Realiseren van de applicatie, (cross)media-uiting
Werkproces 2.1 Legt een gegevensverzameling aan
Doel: Aantonen van kennis van het bewerken en analyseren van data
Input: Functioneel Ontwerp en Technisch Ontwerp
Output: Digitaal formaat met data
Beoordeling: Projectbegeleider
Voor wie: Teamleden
Fysiek bewijs in digitaal formaat:
- Database aanmaken
- Back up/dump van database
- Database moet op zijn minst gevuld zijn met voorbeeld data
Werkproces 2.3 Realiseert een (cross)media uiting en/of systeem
Doel: Aantonen dat je in staat bent om te programmeren volgens documentatie en planning
Input: FO, TO en planning
Output: Digitaal formaat met data, screenshots van het systeem en een realisatieverslag
Beoordeling: Projectbegeleider
Voor wie: Teamleden
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
Werkproces 2.5 Test het ontwikkelde product
Input: Testplan uit het Functioneel Ontwerp en TO
Output: Acceptatietestrapport
Beoordeling: Projectbegeleider
Voor wie: De opdrachtgever
Acceptatietestrapport:
- Beschrijving van wat je gaat testen zoals beschreven in FO
- Overzicht van testers en hun inzet
- Uitvoeren van de test
- Screenshots van het testen (eventuele foutmeldingen)
- Verzamelen testresultaten en verbeteringen beschrijven
- Uitvoeren van de verbeteringen
Werkproces 2.6 Optimaliseert de game of (cross)media-uiting
Input: Acceptatietestrapport
Output: Optimalisatieplan
Beoordeling: Projectbegeleider vervolgens opdrachtgever
Voor wie: Opdrachtgever en teamleden
Optimalisatieplan:
- Gebruiksvriendelijkheid rapport
- Toegankelijkheid rapport
- Overzicht zoekmachine instellingen
Werkproces 2.7 Bewaakt de voortgang en evalueert het project
Input: Plan van aanpak en teamvergaderingen
Output: Actuele gedetailleerde activiteitenplanning en Evaluatie
Beoordeling: Projectbegeleider
Voor wie: Opdrachtgever en teamleden
Actuele gedetailleerde activiteitenplanning:
- Teamleden
- Tijdindeling
- Meetpunten
Evaluatie
- Verzamelen teamfeedback betreft jouw eigen inzet en verbeterpunten beschrijven
Kerntaak 3: Implementeren van de applicatie of (cross)media-uiting
Werkproces 3.1 Maakt of levert een bijdrage aan het implementatieplan
Input: De gerealiseerde applicatie
Output: Implementatieplan en presentatie
Beoordeling: Projectbegeleider en opdrachtgever
Voor wie: Systeem- en/of Applicatiebeheerder van de productieomgeving
Implementatieplan:
Beschrijf het volgende:
- Ingrijpende veranderingen in de organisatie
- Hoe en wie de gegevens gaan converteren, importeren of invoeren
- Procedures en verantwoordelijkheden
- Uitrol(deploy) aanpak(big bang, gefaseerd, parallel, gecombineerd?)
- Stappen in de vorm van een draaiboek op basis van tijd
- Alle te installeren hard- en software
- Infrastructuur, Servers(Web, DB, Mail etc.) en modules
- Systeemtest
- Beheerders training bij ingrijpende veranderingen
- Te verwachten toekomstige applicatie-, gegevens- en technisch beheer
Presentatie hand-out
- Presentatie van het implementatieplan aan projectbegeleider, opdrachtgever en betrokken medewerkers
Werkproces 3.3 Implementeert een applicatie of (cross)media-uiting en/of -systeem
Input: Implementatieplan
Output: Implementatierapport
Beoordeling: Projectbegeleider
Voor wie: Systeem- en/of Applicatiebeheerder van de productieomgeving
Implementatierapport:
- Uitvoeren en documenteren van installatie volgens implementatieplan in samenwerking met beheerder
Werkproces 3.4 Evalueert een implementatie
Input: Implementatieplan en uitkomst van implementatie
Output: Rapport met conclusies en verbeterpunten en procesverslag
Beoordeling: Projectbegeleider en opdrachtgever
Voor wie: Toekomstige beheerders en ontwikkelaars
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
Kerntaak 4: Onderhouden en beheren van de applicatie, (cross)media-uiting
Werkproces 4.1 Onderhoudt applicaties of (cross)media-uiting
Input: Functioneel ontwerp
Output: Onderhoud- en beheerplan, Rapport over de uitvoering van het onderhoud
Beoordeling: Projectbegeleider en opdrachtgever
Voor wie: Systeem- en/of Applicatiebeheerders en toekomstige ontwikkelaars
Onderhoud- en beheerplan:
- Beschrijven, uitvoeren(en documenteren) van procedures voor:
- preventief onderhoud zoals updates, monitoring en unit-tests
- virus bescherming
- back-up en restore
- incidenten-registratie
- (nieuwe) eisen en wensen registratie
- Rapporteren van alle ondernomen stappen en vervolgacties aan opdrachtgever/projectbegeleider
Werkproces 4.2 Verzamelt, controleert, bewerkt en archiveert (cross)mediabestanden
Input: Alle projectdocumenten
Output: Resultaat opnemen in het onderhoud- en beheerplan en het archief
Beoordeling: Projectbegeleider
Voor wie: Toekomstige beheerders en ontwikkelaars
Archivering (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
Archief:
- Digitaal formaat
Werkproces 4.3 Bewaakt de samenhang van media-uitingen
Input: De gerealiseerde applicatie
Output: Resultaat opnemen in het onderhoud- en beheerplan
Beoordeling: Projectbegeleider en opdrachtgever
Voor wie: Toekomstige beheerders en ontwikkelaars
Media-uitingen:
- Audio en visuele stijl samenhang controle(sluit de stijl aan bij andere media-uitingen van de opdrachtgever)
- Advies over andere (sociale)media mogelijkheden
Werkproces 4.4 Stelt script samen ten behoeve van het samenvoegen van content
Input: De gerealiseerde applicatie
Output: Resultaat opnemen in het onderhoud- en beheerplan
Beoordeling: Projectbegeleider en opdrachtgever
Voor wie: Toekomstige beheerders en ontwikkelaars
Opmaak:
- Weergave en uitleg van gebruikte opmaak/gridsysteem/theme/template
Werkproces 4.5 Beheert de content
Input: Onderhoud- en beheerplan
Output: Resultaat opnemen in het onderhoud- en beheerplan en fysiek bewijs in digitaal formaat met screenshots van het systeem
Beoordeling: Projectbegeleider
Voor wie: Toekomstige gebruikers, beheerders en ontwikkelaars
Contentbeheer:
- Korte beschrijving van de route die content aflegt vanaf creatie tot publicatie
- Beschrijving van verdeling van rollen, rechten en verantwoordelijkheden
- Beschrijving van procedures/regels voor aanleveren van bruikbare content
- Gebruikershandleiding en instructies van de wijze waarop content in de applicatie(s) wordt bewerkt en ingebracht
- Bewerking van analoge naar digitale content (scannen, converteren, etc.)
Beoordeling communicatie
Tijdens het beoordelen van de communicatie wordt er op de volgende punten gelet:
- Zijn er vooraf afspraken over onderlinge normen en waarden gemaakt?
- Hoe is er met problemen om gegeaan?
- Welke communicatiemiddelen zijn er gebruikt?
- Hoe is de samenwerking verlopen?
- Voelen de teamleden zich serieus genomen?
- Is een ieders mening en idee welkom?
- Is er voldoende motivatie- of vaardigheid?
- Worden hoofd- en bijzaken herkend?
- Is er gebruikt gemaakt van LSD:)(Luisteren, Samenvatten en Doorvragen)
Beoordeling documentatie
Tijdens het beoordelen van de documentatie wordt er op de volgende punten gelet.
| Onderdeel: | Uitleg: |
|---|---|
|
Titelblad: |
een duidelijk voorblad met daarop vermeld:
|
| Inhoudsopgave: |
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. |
|
Voorwoord: |
hierin behandel je zaken die niet rechtstreeks in verband staan met het onderwerp zoals:
|
|
Inleiding: |
een definitie en afbakening van het onderwerp:
Opmerking: het voorwoord en de inleiding mogen op 1 pagina worden gezet. |
|
Kern: |
de antwoorden op alle vraagstukken en opdrachten:
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:
|
|
Slot: |
Dit is het laatste hoofdstuk waarin:
|
|
Bronvermelding: |
|
|
De verzorging: |
Verwijzingen en/of voetnoten dienen steeds op dezelfde wijze te zijn aangegeven. |
|
Algemeen |
Wanneer je informatie van Internet haalt let dan op het volgende:
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 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.
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:
Zie verder voor de conventies van coderen:
http://framework.zend.com/manual/1.12/en/coding-standard.coding-style.html
4 timebox
