Guide: Vejledning om dokumentation af udviklingssarbejde

From rtgkomArkiv
Jump to: navigation, search

Indtil videre, forklaring og forbehold[edit]

Her er et udkast til en vejledning om hvordan du kan dokumentere dit arbejde når du udvikler IT-produkter i projekter i RTG-MediaLab. Vejledningen er lavet med henblik på at du lærer dig en fremgangsmåde som virker godt i eksamensprojekter i fagene Informationsteknologi B og Programmering C.

Indtil videre består denne artikel af kopier af tekststykker som jeg har skrevet om dette emne i de forskellige holds wiki-artikler i løbet af de sidste ca. fem år. Jeg har selvfølgelig tænkt mig at redigere artiklen og fjerne duppleret tekst.

Indeholdet i denne artikel er tæt relateret til det begrebssystem som vi vælger at bruge om systemudvikling, og derfor kan der være flere henvisninger til både MediaLab's egen systemudviklingsmetode og andre mere kendte metoder, som for eksempel Extreme Programmering.


Efterfølgende er kopieret fra: http://www.rtgkom.dk/mediawiki/index.php?title=2012PrgC336

Resurseplanlægning[edit]

Med hensyn til registrering, altså synliggørelse, af planlægningsarbejdet, både mht. klassisk tidsplanlægning og også den lidt mere præcise og tekniske tilgang som jeg kalder for resurseplanlægning, så kan det være en god ide at bruge et specielt planlægningsværktøj som f.eks. programmet Planner, https://live.gnome.org/Planner. Det laver gantt-kortet automatisk når I har defineret resurser og tasks (aktiviteter) og man kan både exportere det som grafik og HTML.

Krav til dokumentation af mindre programmer[edit]

Når vi skal dokumenter udvikling af programmer, så kan vi bruge følgende liste over krav til dokumentationen som inspiration. For nogle programmer vil det være mindre meningsfuldt at bruge alle punkterne i listen, og for andre programmer vil der måske behøves tiltag som ikke nævnes i listen. Brug den som inspiration, vælg selv de punkter som du synes relevante for dit program:

  1. User stories, en eller flere, som beskriver brugernes forventninger til programmet. Her er nogle eksempler.
  2. Kerneproblemet (evt. flere problemer). Beskrivelse i prosa, på dansk!, af kerneproblemet, altså det eller de problemer som du skal løse for at komme i gang med programmeringen af den første prototype. (Dette krav er inspireret af "Bottom Up" tilgangen til programmering.)
  3. Beskrivelse af brugerfladen for programmet (tekst UI, eller GUI). Tegn en eller flere skitser!
  4. Use Case diagram, som visualiserer hvem skal bruge programmet og til hvad det skal bruges. Her kan f.eks. ArgoUML eller Dia bruges. Sparxsystems har en beskrivelse af opbygningen i de forskellige UML-diagrammer.
  5. Klassediagram, som viser de vigtigste klasser i programmet. Her kan f.eks. ArgoUML eller Dia bruges.
  6. Input. En beskrivelse af input (inddata) til programmet. Hvilke data, deres datatype og mening for brugeren.
  7. Operationer på inddata, altså en beskrivelse af de operationer som programmet skal udføre på inddata.
  8. Output. Beskrivelse af output (uddata) fra programmet. Hvilke data, deres datatype og mening for brugeren.
  9. Flowchart (rutediagram) som viser programmets logiske opbygning/struktur. (Flowcharting, flowchart, brug gerne programmet Dia og for Dia til Windows se her.
  10. Kildekoden for det færdige program, formateret med en non-proportional font, altså med et skriftsnit hvor alle bogstaver er lige brede. Det bevirker at indrykninger i kildekoden ikke forvanskes. Prøv også at bruge ikke større bogstaver end 12 punkter, evt. kun 10 punkter hvis der er mange lange linier i kildekoden som ellers ville deles på to linier (wrap to the next line).
  11. Skærmbilleder som viser/dokumenterer hvordan det færdige program bruges/virker. Husk at i Windows så kan det det valgte, eller aktive vindue, kopieres til klippebordet (clipboard) med tastkombinationen Alt+PrtScr. Det kan være praktisk for at undgå at skulle paste skærmbilledet ind i et billedredigeringsprogram alene for manuelt at klippe vinduet ud fra hele skærmbilledet.
  12. Et skærmbilled, eller flere, som viser udviklingsmiljøet, kildekoden, Python shell'en og evt. debuggeren i funktion med en kort kommentar/forklaring.
  13. Diskussion/beskrivelse af de sætninge (statements) og evt. funktioner i Python som du har brugt i dit program.
  14. Diskussion/beskrivelse af de eksterne funktionsbiblioteker (Python moduler) du evt. har brugt i dit program.


Efterfølgende er kopi fra: http://www.rtgkom.dk/wiki/2011PrgC34

Generelle krav til dokumentation af projektopgaver i Programmering C, 2011-10-04, Gkb[edit]

Når vi skal dokumenter udvikling af programmer, så kan vi bruge følgende liste over krav til dokumentationen som inspiration. For nogle programmer vil det være mindre meningsfuldt at bruge alle punkterne i listen, og for andre programmer vil der måske behøves tiltag som ikke nævnes i listen. Brug den som inspiration, vælg selv de punkter som du synes relevante for dit program:

  1. User stories, en eller flere, som beskriver brugernes forventninger til programmet. Her er nogle eksempler.
  2. Kerneproblemet (evt. flere problemer). Beskrivelse i prosa, på Dansk!, af kærneproblemet, altså det eller de problemer som du skal løse for at komme i gang med programmeringen af den første prototype. (Dette krav er inspireret af "Bottom Up" tilgangen til programmering.)
  3. Beskrivelse af brugerfladen for programmet (tekst UI, eller GUI). Tegn en eller flere skitser!
  4. Use Case diagram, som visualiserer hvem skal bruge programmet og til hvad det skal bruges. Her kan f.eks. ArgoUML eller Dia bruges. Sparxsystems har en beskrivelse af opbygningen af de forskellige UML-diagrammer.
  5. Klassediagram, som viser de vigtigste klasser i programmet. Her kan f.eks. ArgoUML eller Dia bruges.
  6. Input. En beskrivelse af input (inddata) til programmet. Hvilke data, deres datatype og mening for brugeren.
  7. Operationer på inddata, altså en beskrivelse af de operationer som programmet skal udføre på inddata.
  8. Vigtige datastrukturer som bruges i programmet, f.eks. lister, records, osv. Evt. også vigtige variabler og konstanter.
  9. Output. Beskrivelse af output (uddata) fra programmet. Hvilke data, deres datatype og mening for brugeren.
  10. Flowchart (rutediagram) som viser programmets logiske opbygning/struktur. (Flowcharting, flowchart, brug gerne programmet Dia og for Dia til Windows se her.
  11. Kildekoden for det færdige program, formateret med en non-proportional font, altså med et skriftsnit hvor alle bogstaver er lige brede. Det bevirker at indrykninger i kildekoden ikke forvanskes. Prøv også at bruge ikke større bogstaver end 12 punkter, evt. kun 10 punkter hvis der er mange lange linier i kildekoden som ellers ville deles på to linier (wrap to the next line).
  12. Skærmbilleder som viser/dokumenterer hvordan det færdige program bruges/virker. Husk at i Windows så kan det valgte, altså det aktive vindue, kopieres til klippebordet (clipboard) med tastkombinationen Alt+PrtScr. Det kan være praktisk for at undgå at skulle paste skærmbilledet ind i et billedredigeringsprogram alene for manuelt at klippe vinduet ud fra hele skærmbilledet.
  13. Et skærmbilled, eller flere, som viser udviklingsmiljøet, kildekoden og f.eks. Python shell'en og evt. debuggeren i funktion med en kort kommentar/forklaring. Hvis du/I har anvendt andre værktøjer, f.eks. Lazarus og POV-Ray, so skal der selvfølgelig også laves skærmbilleder som viser dem under aktiv udvikling af jeres program.
  14. Diskussion/beskrivelse af de sætninge (statements) og evt. funktioner i Python/POV-Ray/Object Pascal (eller det sprog som du/I nu har valgt ) som bruges i dit/jeres program.
  15. Diskussion/beskrivelse af de eksterne funktionsbiblioteker (Python moduler, Object Pascal units, POV-Ray include filer, osv.) du evt. har brugt i dit program.

Som inspiration til rapportskrivningen kan vores generelle guide om projektbeskrivelse og rapport evt. bruges, se her http://rtgkom.dk/wiki/Guide:Projektbeskrivelse_og_rapport