Systemutvikling og dokumentasjon

University College of Southeast Norway Systemutvikling og dokumentasjon Eksempler på dokumenter i et Software-prosjekt Hans-Petter Halvorsen, 2017.01.12 http://home.hit.no/~hansha

Forord Dette dokumentet tar for seg ulike former for dokumentasjon i et systemutviklingsprosjekt. Typisk utvikles det forskjellige typer dokumenter i de ulike fasene som inngår i Software-utvikling. Se Figur nedenfor. Det er viktig å huske på at all dokumentasjon lager man fordi den er nyttig og skal brukes gjennom hele utviklingsprosjektet samt i forbindelse med installasjon og bruk i etterkant, både av kunden og ifm. vedlikehold og videreutvikling av systemet. All dokumenter som lages må brukes aktivt underveis i prosjektet, samt at disse må oppdateres og vedlikeholdes kontinuerlig. Alle dokumenter må selvfølgelig ligge i et dokumenthåndteringssystem, f.eks. Visual Studio Team Services (VSTS). ii

Table of Contents Forord... ii Table of Contents... iii 1 Innledning... 5 1.1 Typisk dokumentleveranse... 7 1.1.1 Process Documentation... 7 1.1.2 Product Documentation... 7 1.1.3 User Documentation... 7 2 Generelt om dokumenter... 8 2.1 Dokumentskriving... 8 3 Product Web Site... 9 3.1 Hensikt med denne websiden... 9 4 Software Development Plan (SDP)... 11 4.1 Hensikten med dokumentet... 11 4.2 Innhold... 12 4.2.1 SDP forslag A... 12 4.2.2 SDP forslag B... 12 5 Software Requirements & Design (SRD)... 14 5.1 Hensikten med dokumentet... 15 6 Software Test Plan (STP)... 16 6.1 Hensikten med dokumentet... 16 6.2 Vedlegg... 18 iii

iv Table of Contents 7 System Documentation... 19 7.1 Large Systems... 19 8 Installation Guide(s)... 21 9 User Guide(s)... 22 References... 23 Vedlegg... 24 Dokumentasjon i Systemutvikling

1 Innledning Typiske dokumenter i et utviklingsprosjekt (Figure 1-1): Figure 1-1: Typisk Software-dokumentasjon Dokumenter kan deles inn i ulike kategorier (Figure 1-2): 5

6 1 Innledning Figure 1-2: Dokument-kategorier Forskjell mellom F1 prosjekt og et Softwareprosjekt (Figure 1-3): Figure 1-3: Software Development Project Vi prøver å gjøre det slik som det gjøres i en virkelig softwareprosjekt. Dokumentasjon i Systemutvikling

7 1 Innledning 1.1 Typisk dokumentleveranse I et utviklingsprosjekt har vi både interne dokumenter (prosess-dokumenter) og eksterne dokumenter (produkt-dokumenter). Nedenfor gis det en kort oversikt over disse variantene. 1.1.1 Process Documentation Typisk Prosess-dokumentasjon: 1. Development Plan (with Gantt Chart, Resources, etc.) 2. Meeting documentation (included in VSO) 3. Requirements & Design Document 4. Test Plan (how to test, etc.) & Test Documentation (#3b) (Test results, etc) 1.1.2 Product Documentation Typisk Produkt-dokumentasjon: 1. System Documentation 1. How the System Works (Technical), i.e. use the Requirements & Design as base. 2. Requirements & Design is about how it should be, while System Documentation is about how it became 3. Includes Technical Design and Platform Overview, Database Diagram, UML diagrams, CAD drawings, Code Documentation, Flow Charts, with explanations, etc. 4. How to deploy (how to install server-side logic), maintain, etc. 1.1.3 User Documentation Typisk User-dokumentasjon: 2. Installation Guide (#5) (you may include it as part of User Manual and/or System Documentation) 3. User Manual(s) (#6) Dokumentasjon i Systemutvikling

2 Generelt om dokumenter Det er ingen fasit mtp utarbeidelse av dokumentasjon, det er mange varianter ute å år. Det er en del grunnleggende ting som går igjen i alle former for dokumenter. 2.1 Dokumentskriving Alt dere har lært om rapportskriving tidligere gjelder også her! Den eneste forskjellen at her er det flere dokumenter istedenfor en rapport. Produktwebsiden blir på en måte selve rapporten, mens SDP, SRD, STP, osv. blir på en måte vedlegg. Dvs. grunnleggende rapporttekniske ting som Tabell og figurnummerering, m.m. må selvfølgelig være med! Typisk struktur: Forside/Tittelside, innholdsfortegnelse, Innledning, en eller flere kapitler med innhold, + evt vedlegg. Bruke nummerering i forbindelse med kapitler og underkapitler er vanlig. Sidenummerering må selvfølgelig være med. Bruke samme Word Template på alle dokumentene! dvs bruk samme fonter, fargebruk, m.m. i de ulike dokumentene. Bruk av referanser der det er bruk kilder, ressurser fra andre. 8

3 Product Web Site I forbindelse med prosjektet skal det lages en såkalt Product Web Site. Ikke glem at kildekoden til denne siden også må ligge i Visual Studio Team Services (VSTS) slik at alle i teamet kan vedlikeholde denne. Nødvendig informasjon og opplæring ifm dette gis når den tid kommer. 3.1 Hensikt med denne websiden Reklamere for/selge produktet til potensielle kjøpere og/eller vise frem produktet/løsningen for kunden som har bestilt det samt dokumentere progresjonen til løsningen underveis slik at kunden er er komfortabel med at utviklingen går som planlagt. Man må ha med en beskrivelse av produktet,samt en eller flere bilder. Ha med litt reklame. Hva er hensikten med produktet, hvem skal bruke det? Hva skal det brukes til, osv. (blir litt som en innledning i en teknisk rapport). I tillegg vil denne websiden være rapporten dere skal levere i slutten av semesteret, hvor tekst og bilder på websiden er innledning, og de andre linkene (SDP, SRD, STP, System Documentation, Installation Guide, User Manual,...) er selve kapitlene eller vedlegg til rapporten. Bruk PDF på de dokumentene som kun skal leses (SDP, SRD, STP,..), mens templater som Test Cases Excel ark, Code Review Template Excel ark må jo selvfølgelig være i orginalformat, da disse skal fulles ut. Figure 3-1 viser et (veldig enkelt) eksempel på hvordan en slik Product Web Site kan se ut. 9

10 3 Product Web Site Figure 3-2 viser et annet forslag. Figure 3-1: Product Web Site Figure 3-2: Final Report Have the Customer in mind. Pretend that this is a real software project and not a school project. Dokumentasjon i Systemutvikling

4 Software Development Plan (SDP) The SDP is also referred to as the Communication Plan or just Project Plan The SDP is a document that describes the Project, Resources, Communication, Schedule (e.g. Gantt chart), Tools, etc. 4.1 Hensikten med dokumentet Inneholde all tenkelig informasjon om hvordan man skal gjennomføre prosjektet, tidsplaner, budsjetter, resurser, software og utviklingsverktøy, osv. Det er meningen at dette skal være et levende dokument som aktivt skal brukes underveis av de involverte i prosjektet, og da særlig utviklingsteamet, men også ledere, beslutningstakere, stakeholders, samt evt kunden. NB! Dette er et dokument som oppdateres kontinuerlig og som må brukes aktivt gjennom hele prosjektet innad i Teamet! Hver gang Gantt diagrammet (MS Project) oppdateres, osv. Må jo også dette dokumentet oppdateres. Elementer som inngikk i en såkalt Gruppeavtale (kjent fra bla. F1 prosjekt) bør/kan inngå som en del av SDP. Bør ha med linker til f.eks: Link til Dokument - Websiden Link til VSTS Prosjekt Link til Wordmaler Osv. 11

12 5 Software Requirements & Design (SRD) 4.2 Innhold Typisk innhold i SDP dokumentet: 4.2.1 SDP forslag A Følgende temaer bør være med[1]: 1. Product Description 2. Team Description 3. Software Process Model Description 4. Project Definition 5. Project Organization 6. Validation Plan 7. Configuration/Version Control 8. Tools 4.2.2 SDP forslag B Følgende temaer bør være med[2]: 1. Introduction: This briefly describes the objectives of the project and set out the constraints (e.g., budget, time, etc.) that affects the management of the project 2. Project Organization (Team Description) This section describes how the development team is organized, the people involved and their roles in the team. Software Process Model Description (Scrum, XP, Waterfall,...), etc. 3. Risk Analysis 4. Hardware and Software Resource Requirements 5. Work Breakdown (WBS, Work Breakdown Structure): Break down the project in into activities and identifies milestones 6. Project Schedule: Shows dependencies between activities, the estimated time required to reach each milestone, allocation of people to activities. (5) and (6) is typically done in a Gantt Chart (created in e.g. Microsoft Project) 7. Monitoring and Reporting Mechanisms: Definition of the Management Report that should be produced, when they should be produced, etc. 8. Tools that you are using Dokumentasjon i Systemutvikling

13 5 Software Requirements & Design (SRD) Dere trenger nødvendigvis ikke følge alternativ A eller B slavisk, dere kan gjerne blande, tilføye eller utelate ting som ikke er relevant for deres prosjekt. Det er viktig at man har med Software arkitektur og oversikt over Software Plattformer, m.m. Gode skisser (Systemoversikt) i forbindelse med dette med ulik detaljeringsgrad for ulike lesere. Dokumentasjon i Systemutvikling

5 Software Requirements & Design (SRD) Requirements (WHAT): WHAT the system should do Describes what the system should do with Words and Figures,etc. SRS Software Requirements Specification Document Software Design (HOW): HOW it should do it Examples: GUI Design, UML, ER diagram, CAD, etc. SDD Software Design Document Note! Many don't separate SRS and SDD documents, but include everything in a Requirements & Design Document (SRD). In practice, requirements and design are inseparable. Figure 5-1 viser typisk innhold i et SRD document. 14

15 5 Software Requirements & Design (SRD) Figure 5-1: SRD Contents 5.1 Hensikten med dokumentet Et løpende dokument som brukes til å gi en oversikt over hva som skal lages (Requirements)/utvikles og hvordan det skal lages/utvikles (Design). Brukes som en kontrakt mellom utviklingsfirma og kunde, samt brukes kontinuerlig av utviklere (når de skal lage/utvikle løsningen), testere (når de skal teste løsningen) og kunde (sike at løsningen blir slik de ønsker) underveis. Mye av innholdet lages i oppstarten av prosjektet (eller i forkant av prosjektet), men innholdet må oppdateres kontinuerlig når endringer oppstår, særlig med med smidig utvikling vil dette være tilfellet. Dokumentasjon i Systemutvikling

6 Software Test Plan (STP) Dokumenter som inngår ifm testing (Figure 6-1): Figure 6-1: Test Documents 6.1 Hensikten med dokumentet Dagens software-systemer er veldig komplekse (se Figure 6-2), derfor kreves det at testing gjennomføres på en strukturert måte. 16

17 6 Software Test Plan (STP) Typisk innhold: Figure 6-2: Komplekse Softwaresystemer Goals and Exit Criteria (Quality, Robustness, Schedule, Performance Goals of the Product,...) Items to be Tested/Inspected (Executables such as modules and components, Nonexecutables such as Requirments and Design specifications,...) Test Process/Methodologies (Unit, Functional, Acceptance, Regression Tests, Black-box, White-box, Test metrics, Bug report process,... ) Resources (People, Tools, Test Environment,...) Schedule (Test-case development, Test execution, Problem reporting and fixing,...) Risks (...) Major Test Scenarios and Test Cases (...) Beskrivelse av Testmiljø, hvor er testmiljøet? hvordan bruker man det? Evt hvordan setter man det opp, osv. Beskrivelse av Prosedyrer for Bugrapportering. Hvor rapporterer man Bugs? Hvordan rapporterer man Bugs? Osv. Dokumentasjon i Systemutvikling

18 6 Software Test Plan (STP) 6.2 Vedlegg Vedlegg : Test Cases dvs f.eks et Excel-ark med mange Test Case på en strukturert måte, bruk gjerne flere ark (sheets). Dokumentasjon i Systemutvikling

7 System Documentation Ta utgangspunkt i SRD. Detaljert beskrivelse av systemet på teknisk nivå. Tip: Make a copy of your SRS/SDD and take it from there (Rename, Add, Delete, Change contents, etc.). How the System Works (Technical), i.e. use the Requirements & Design as base. Requirements & Design Documents is about how it should (planned to) be, while System Documentation is about how it became Includes Technical Design and Platform Overview, Database Diagram, UML diagrams, CAD drawings, Code Documentation, Flow Charts, with explanations, etc. How to deploy (how to install server-side logic), maintain, etc. System documentation includes all of the documents describing the system itself from the requirements specification to the final acceptance test plan. Documents describing the design, implementation and testing of a system are essential if the program is to be understood and maintained. Like user documentation, it is important that system documentation is structured, with overviews leading the reader into more formal and detailed descriptions of each aspect of the system. Beskrivelse av Enhetstester, Testmiljø, mm. 7.1 Large Systems For large systems that are developed to a customer s specification, the system documentation should include: 1. The requirements document. 2. A document describing the system architecture. 19

20 6 Software Test Plan (STP) 3. For each program in the system, a description of the architecture of that program. 4. For each component in the system, a description of its functionality and interfaces. 5. Program source code listings, which should be commented where the comments should explain complex sections of code and provide a rationale for the coding method used. If meaningful names are used and a good, structured programming style is used, much of the code should be self documenting without the need for additional comments. This information is now normally maintained electronically rather than on paper with selected information printed on demand from readers. 6. Validation documents describing how each program is validated and how the validation information relates to the requirements. These may be required for the quality assurance processes in the organization. 7. A System Maintenance Guide, which describes known problems with the system, describes which parts of the system are hardware and software dependent and which describes how evolution of the system has been taken into account in its design Dokumentasjon i Systemutvikling

8 Installation Guide(s) Hvordan installerer man programvaren? Steg for steg, med bilder, osv. Eksempel på innhold: Prerequisites What need to be in place before you start the installation, e.g., OS version, Drivers,.NET Framework,... Where do you find the Installation Files/packages Step-by-step Guide of how to install the Software (Text + Figures) How do you start your Application(s) when you are finished with the installation How do you uninstall the software?... 21

9 User Guide(s) Hvordan bruker man programvaren? A user manual often include: A cover page A title page and copyright page A preface, containing details of related documents and information on how to navigate the user guide A contents page A guide on how to use at least the main functions of the system (Text + Screen Shots) A troubleshooting section detailing possible errors or problems that may occur, along with how to fix them A FAQ (Frequently Asked Questions) Where to find further help, and contact details A glossary and, for larger documents, an index En brukermanual kan være så mangt, f.eks et Word dokument (->PDF), en online hjelpefil eller webside, en eller flere videoer, osv. 22

References [1] F. Tsui, O. Karam, and B. Bernal, Essentials of Software Engineering, 3 ed.: Jones & Barlett Learning, 2014. [2] I. Sommerville, Software Engineering, 10 ed.: Pearson, 2015. [3] E. J. Braude and M. E.Bernstein, Software Engineering: Modern Approaches, 2 ed.: Wiley, 2011. 23

Vedlegg 24

Hans-Petter Halvorsen, M.Sc. E-mail: hans.p.halvorsen@hit.no Blog: http://home.hit.no/~hansha/ University College of Southeast Norway www.usn.no