Anonim

Da applikationer er blevet skrevet og betjent, er der dokumenter: projektdokumentation til udvikling og driftsdokumentation til drift af applikationer. Deres oprettelse er en upopulær aktivitet, der ofte udsættes eller undertiden helt elimineres, fordi budgettet allerede er opbrugt. Hver af os ved, hvor vigtig dokumentation er - for eksempel når applikationer overføres fra en tjenesteudbyder til en anden, eller når nye medarbejdere vil gøre sig bekendt med den.

Dokumentationen sollten sich auf das Nötigste beschränken. Versionssicherheit ist wichtig, außerdem sollten Texte und Diagramme durchsuchbar und einzelne Elemente logisch miteinander verlinkt sein. Tools wie JIRA oder Confluence können helfen, Dokumentationen moderner zu gestalten.
Dokumentationer bør begrænses til det væsentlige. Versionssikkerhed er vigtig, og tekst og diagrammer skal være søgbare og individuelle elementer logisk forbundet. Værktøjer som JIRA eller Confluence kan hjælpe med at gøre dokumentationen mere moderne.
Foto: Alexander Supertramp - shutterstock.com

Dokumentation, især fra store, modne, missionskritiske systemer, er ofte i en beklagelig tilstand. For at holde det opdateret kræver vi i vores erfaring i gennemsnit fem til ti procent af de samlede omkostninger til udviklingsprojekter. De fleste operationelle ledere af forretningskritiske applikationer vil svare - stillet spørgsmål om kvaliteten af ​​dokumentationen - "utilstrækkelig". Så hvis dokumentationen er dårlig, men vigtig og frem for alt dyr, hvordan kan den forbedres? Virksomheder kan starte med HVAD og HVORDAN.

spoods.de

Til HVAD

En applikation har altid to typer dokumentation: den vedvarende dokumentation, der kortlægger hele applikationen i dens aktuelle tilstand, og den midlertidige eller projektdokumentation, der beskriver en ændring.

Den permanente dokumentation er en statisk henvisning til ansøgningen. Målet med den midlertidige dokumentation er at understøtte den kreative og samarbejdende udviklingsproces. Det fremgår af disse forskellige mål, at den ene dokumentation ikke samtidig kan tjene formålet med den anden.

Den permanente dokumentation bruges for eksempel til følgende opgaver:

  • Forretningsproces, som applikationen understøtter,

  • Funktioner / funktionelle enheder,

  • Krav i regulerede miljøer

  • Kontekstdiagram / komponentdiagram,

  • teknisk arkitektur,

  • regressionstest

  • Betjeningsvejledning,

  • Bruger.

Midlertidig dokumentation bruges, når det drejer sig om følgende opgaver:

  • Krav / brugerhistorier,

  • Specifikationer / kravspecifikation,

  • Design / tekniske specifikationer,

  • Database model,

  • Klasse diagram,

  • Test tilfælde, test dokumentation.

  • Release notes.

FOR HVORDAN

For at dokumentere applikationens aktuelle tilstand er der to tilgange. På den ene side kan den permanente dokumentation være indsamling af midlertidige dokumenter. Dette sparer tid i oprettelsen, men er permanent uleselig: Hvis læseren vil vide, hvorfor en funktion er som den er, skal den læse hele dokumentationen baglæns, indtil den finder dokumentet, der beskriver installationen af ​​denne funktion,

I den anden variant opdateres den permanente dokumentation efter afslutningen af ​​hver ændring. Til dette formål er kun permanent relevant information hentet fra den midlertidige dokumentation. Dette er detaljerede, men lettere at læse.

For HVORDAN er det også vigtigt, hvordan dokumentationen gemmes. Dette sker normalt i form af forskellige dokumenter (for eksempel i Word) på en fælles platform, f.eks. SharePoint. Så et stort antal dokumenter mødes, som er samarbejdsvilligt at arbejde med, men dokumenterne er svære at søge, ikke knyttet til hinanden, og deres version er muligvis ikke opdateret.

Disse aspekter er dog især vigtige for moderne og fremtidssikker dokumentation. Det handler om god søgbarhed, sammenkobling (for eksempel mellem testsager og krav og mellem diagrammer og prosatekster, der beskriver dem) og version af sikkerhed. Det er også i udviklerens interesse at dokumentere lidt samlet, at fokusere på det væsentlige og klare sig med blot et par dokumenter. Hvordan kan det opnås?

Fra vores synspunkt er de væsentligste elementer i god, permanent dokumentation:

  • En kort beskrivelse af applikationsfunktionerne: Hvad gør systemet? Hvilken forretningsproces understøtter den? Hvilke funktioner tilbyder det? Denne beskrivelse af de tekniske krav kan være rent tekstuelt. Derudover anbefales et professionelt enhedsdiagram, også et kontekstdiagram er nyttigt.

  • Også vigtig er listen over krav, der hører til de eksisterende funktioner. Det hjælper med at forstå, hvorfor en bestemt funktion er nødvendig.

  • Selv en beskrivelse af den tekniske arkitektur, der er begrænset til det væsentlige, er uundværlig: Hvordan er systemet struktureret? Her er diagrammer især nyttige: kontekstdiagrammer, komponentdiagrammer og illustrationer af den tekniske arkitektur.

  • Endelig er der behov for regressionstest som et værktøj til sikkert at foretage ændringer i applikationen. Alle ændringer gennemgår et sæt sæt regressionstesttilfælde inden deres integration i applikationen, der dækker alle væsentlige funktioner i systemet. Hver regressionstesttilfælde skal henvise til et eller flere krav, som det vil verificere. Dette sikrer, at enhver ændring, der påvirker alle tilfælde af regressionstest, ikke skader applikationens funktionalitet.

Når det kommer til den midlertidige dokumentation, skal den opfylde kravene til udvikling og være designet til let integration i permanent dokumentation. Helt nødvendigt her er:

  • en beskrivelse af de nye og ændrede krav i samme form og nomenklatur (for eksempel nummerering) som i den permanente dokumentation;

  • Ændringer i diagrammet med funktionel enhed: Det kan bruges fra den permanente dokumentation, og kun ændringerne indtastes og fremhæves;

  • Ændringer af kontekstdiagrammet;

  • Ændringer i den tekniske arkitektur;

  • muligvis andre midlertidige dokumenter, der er nødvendige for udvikling, såsom offshore (databasemodeller, klassediagrammer osv.);

  • Testtilfælde (inklusive regressionstestsager), der henviser til anmodninger.

Efter afslutningen af ​​udviklingsprojektet kan den permanente dokumentation let tilpasses fra de midlertidige dokumenter. Derefter opdateres dokumenterne og gøres tilgængelige i en ny version.

Den nye HVORDAN

Er der stadig spørgsmålet om en mere moderne HVORDAN. Dokumentationen kan stadig være i form af Word og andre dokumenter. Dette kan i det mindste produceres manuelt version af sikkerhed. Søgbarhed og linkbarhed er stadig ikke der, hvilket gør brugen af ​​dokumentation meget vanskeligere.

Derfor anbefales det at bruge mulighederne for værktøjer som JIRA eller Confluence til dokumentationen. Tekst og diagrammer kan søges, individuelle elementer kan forbindes, f.eks. Testtilfælde eller krav. For eksempel, hvis du leder efter virkningerne af en fiasko i drift, vil det være lettere at finde det tilhørende krav, og du kan bedre estimere virkningen af ​​fejlen. For at producere versionssikkerhed her er det stadig nødvendigt, efter ændringen, at fratrække den aktuelle status for dokumentationen.

Det lønner sig bestemt ikke at omarbejde omfattende eksisterende dokumentation for store systemer på denne måde. Imidlertid sparer dem, der starter med nye systemer med økonomisk dokumentation i denne forstand en stor indsats nu og i fremtiden. (Hv)