WeekAssignment - Software Documentationhome.hit.no/~hansha/documents/subjects/IA4412/week_assignments...Sharing Documents Google Docs ... Software Documentation Requirements ... SRS

WeekAssignmentSoftwareDocumentation

Hans-PetterHalvorsenB.Lund.Lunch.Available:http://www.lunchstriper.no,http://www.dagbladet.no/tegneserie/lunch/

2017.04.25

WeekAssignment

1. CreateSystemDocumentation2. CreateUserManual(s)s

SeeNextSlidesformoredetails...

AllDocuments,Code,etc.shouldbeuploadedtoVisualStudioTeamServices(VSTS)

NextWeek:Installation(Deployment)andInstallationGuide(s),etc.

+ContinuewithImplementation,TestingandBugFixing!!– Iteration#3

Introduction

Hans-PetterHalvorsen,M.Sc.

SoftwareDocumentation

TypicalSoftwareDocumentation

High-LevelRequirementsandDesignDocuments

UserManuals

SystemDocumentation

InstallationGuides

TestPlans

TestDocumentation

DetailedRequirementsandDesignDocuments

ERDiagram(Database)UMLDiagrams(Code)

Time

Start

Finish

HowtoTest/WhattoTest

CADDrawings,etc.

1.Planning

2.Testing

3.End-userDocumentation(Thepeoplethatshallactuallyusethesoftware)

TechnicalStuff

HowtouseitHowtoinstallit

Proofthatyouhavetestedandthatthesoftwareworksasexpected

(Thestakeholders,thesoftwareteam;architects,UXdesigners,developers)

(QApeople)

(SuperUser/ITdep.)

WHATHOW

(EndUser)

ProjectM

anagem

ent(Ga

nttC

hart,etc.)

(SRS)(SDD)

(STP)(STD)

SoftwareDevelopmentPlan

(SDP)

2.Requierements/Design

DocumentLocation?• WewilluseVisualStudioTeamServices(VSTS)tostoreandshareProjectPlanningandSourceCode

• WeshouldalsoshareRelease/FinalDocuments(Wordfiles,Excelfiles,Visiofiles,etc.)inVSTS

• WhileWorkingdocumentsmaybestoredinOneDrive(Word/Exceldocs)orGoogleDocstomakeiteasyfortheTeamtoworkonthesamedocumentssimultaneouslyinrealtime.

SharingDocumentsGoogleDocs

Word+OneDrive

TheTeamcanCollaborateandEditDocumentsSimultaneously

DocumentationisImportant!

B.Lund.Lunch.Available:http://www.lunchstriper.no,http://www.dagbladet.no/tegneserie/lunch/

RequirementsAnalysis

Design

Implementation

Testing

Maintenance

Planning

YourSoftwarewithDocumentation

Deployment

SRS

SDD

STD

Code

InstallationGuides

UserGuides

GanttChart

withERDiagram,UMLDiagrams,CADDrawings

TestDocumentation

SoftwareRequirementsSpecifications

SoftwareDesignDocumentsSystemDocumenation

SoftwareTestPlan

ProjectPlanning

End-UserDocumentation

SystemDocumentation

SoftwareTestDocumentation

SDPSoftwareDevelopment

Plan

STP

SoftwareProjectDocumentationDocumentationproducedduringasoftwareProjectcanbedividedinto2Categories:• Process Documentation

– Thesedocumentsrecordtheprocessofdevelopmentandmaintenance,e.g.,Plans(SoftwareDevelopmentPlan,SoftwareTestPlan,...),Schedules(e.g.,GanttCharts),etc.

• Product Documentation– Thesedocumentsdescribetheproductthatisbeingdeveloped.Can

bedividedinto2subcategories:• System Documentation

– Usedbyengineersdevelopingandmaintainingthesystem• User Documentation

– Usedbythepeoplethatisusingthesystem

ProcessDocumentation

ProductDocumentation

SystemDocumentation

UserDocumentation

ProjectDocumentation

SoftwareDocumentationCategories

ProjectPlan,GantChart,MeetingDocuments,Requirements&Designdocumentation,Emails,Testdocuments,otherkindofWorkingDocuments,etc.

UserManual,Wikis,OnlineHelp,etc.

TechnicalDocumentationneededinordertomaintainthesoftware,etc.

InstallationGuides

SoftwareProcess Documentation1. SoftwareDevelopmentPlan(SDP)2. SoftwareRequirementsSpecifications

(SRS)3. SoftwareDesignDocuments(SDD)4. SoftwareTestPlan(STP)/SoftwareTest

Documents(STD)

11

Thoseweare“Finished”with– NextStepistocreatetheProduct Documentation



SystemDocumentation

UserDocumentation

ProjectDocumentation

SoftwareDocumentationCategories

ProjectPlan,GantChart,MeetingDocuments,Requirements&Designdocumentation,Emails,Testdocuments,otherkindofWorkingDocuments,etc.

UserManual,Wikis,OnlineHelp,etc.

TechnicalDocumentationneededinordertomaintainthesoftware,etc.

InstallationGuides

SoftwareDocumentationRequirements• Shouldactasacommunicationmediumbetweenmembersofthe

DevelopmentTeam(ProcessDocumentation)• InformationrespositoryusedbyMaintenanceEngineers(Product

Documentation)• InformationforManagementtohelpthemPlan,BudgetandSchedulethe

SoftwareDevelopmentProcess(ProcessDocumentation)• Someofthedocumentsshouldtellusershowtouseandadministerthe

system(ProductDocumentation)• DocumentsforQualityControl,SystemCertification,etc.(Process/Product

Documentation)

=>SatisfyingtheserequirementsrequiresdifferenttypesofdocumentsfrominformalworkingdocumentsthroughprofessionallyproducedUserManuals

• Usersofasystemarenotallthesame.• Theproducerofdocumentationmuststructureittocaterfordifferentuser

tasksanddifferentlevelsofexpertiseandexperience.• Itisparticularlyimportanttodistinguishbetweenend-usersandsystem

administrators:1. End-usersusethesoftwaretoassistwithsometask.

– Thismaybeflyinganaircraft,managinginsurancepolicies,writingabook,etc.Theywanttoknowhowthesoftwarecanhelpthem.Theyarenotinterestedincomputeroradministrationdetails.

2. SystemAdministratorsareresponsibleformanagingthesoftwareusedbyend-users.– Thismayinvolveactingasanoperatorifthesystemisalargemainframesystem,as

anetworkmanageristhesysteminvolvesanetworkofworkstationsorasatechnicalguruwhofixesend-userssoftwareproblemsandwholiaisesbetweenusersandthesoftwaresupplier.

UserDocumentationReaders

SystemDocumentation

• CreateSystemDocumentationforyourSystems.• Itcanbeoneormoredocuments• Tip:MakeacopyofyourSRS/SDDandtakeitfromthere(Rename,Add,Delete,Changecontents,etc.).

SeeNextSlidesformoredetails...

Thepointofnoreturnisthepointbeyondwhichonemustcontinueonone'scurrentcourseofactionbecauseturningbackisphysicallyimpossible,prohibitivelyexpensive,ordangerous

ProjectStart

ProjectEnd

PointofnoReturn



ProcessDocumentation ProductDocumentation

SDP- SoftwareDevelopmentPlanSRS– SoftwareRequirementsandSpecificationSDD– SoftwareDesignDocumentSRD– SoftwareRequirementsandDesignSTP– SoftwareTestPlanSTD– SoftwareTestDocumentation

SDP SRS SDD

SRD

STP STD

Alpha Beta RC RTM

SystemDocumentation

UserManual(s)

InstallationGuide(s)

Feature/CodeFreezeMakenonewFeatures- onlyFinishwhatyouhavestarted

Start Finished

SoftwareRequirementsandDesign(SRD) SystemDocumentation

Feature/CodeFreezeMakenonewFeatures- onlyFinishwhatyouhavestarted

SystemDocumentation

Howshoulditbe? Howitbecame

StopupdatingSRD MakeacopyofSRDandrenametheDocument.

AddCodeDocumentation,UnitTesting,etc.

ProcessDocumentation ProductDocumentation

SystemDocumentation• HowtheSystemWorks(Technical),i.e.usethe

Requirements&Designasbase.• Requirements&DesignDocumentsisabouthowit

should(plannedto)be,whileSystemDocumentationisabouthowitbecame

• IncludesTechnicalDesignandPlatformOverview,DatabaseDiagram,UMLdiagrams,CADdrawings,CodeDocumentation,FlowCharts,withexplanations,etc.

• Howtodeploy(howtoinstallserver-sidelogic),maintain,etc.

• CodeDocumentation,UnitTestingDocumentation

SystemDocumentation• Systemdocumentationincludesallofthedocumentsdescribingthesystemitselffromtherequirementsspecificationtothefinalacceptancetestplan.

• Documentsdescribingthedesign,implementationandtestingofasystemareessentialiftheprogramistobeunderstoodandmaintained.

• Likeuserdocumentation,itisimportantthatsystemdocumentationisstructured,withoverviewsleadingthereaderintomoreformalanddetaileddescriptionsofeachaspectofthesystem.

ImplementationandCode

• DocumentationoftheCodeisanimportantpartoftheSystemDocumentation

• UnitTestingshouldalsobepartoftheSystemDocumentation


SystemDocumentation

UserManual/Guide• CreateoneormoreUserManualsforyourSystem

• YoutypicallycreateoneUserManualforeachModule

• ItcanbeanordinaryWord/PDFFile,oritcanbeonlinehelp(Web,HTML),Video(s),etc.

UserManual/Guide

Thesectionsofausermanualofteninclude:• Acoverpage• Atitlepageandcopyrightpage• Apreface,containingdetailsofrelateddocumentsandinformationonhowtonavigatetheuserguide• Acontentspage• Aguideonhowtouseatleastthemainfunctionsofthesystem(Text+ScreenShots)• Atroubleshootingsectiondetailingpossibleerrorsorproblemsthatmayoccur,alongwithhowtofix

them• AFAQ(FrequentlyAskedQuestions)• Wheretofindfurtherhelp,andcontactdetails• Aglossaryand,forlargerdocuments,anindex

http://en.wikipedia.org/wiki/User_guide

Auserguideoruser'sguide,alsocommonlyknownasamanual,isatechnicalcommunicationdocumentintendedtogiveassistancetopeopleusingaparticularsystem.Itisusuallywrittenbyatechnicalwriter,althoughuserguidesarewrittenbyprogrammers,productorprojectmanagers,orothertechnicalstaff,particularlyinsmallercompanies.

OurFocus

Ifthedocumentationisnotuseful– dont makeit!!

SoftwareDocumentation


Hans-PetterHalvorsen

UniversityCollegeofSoutheastNorwaywww.usn.no

E-mail:[email protected]:http://home.hit.no/~hansha/Blog:http://www.halvorsen.blog