software documentation overview - telemark university...

Hans-PetterHalvorsen,M.Sc.

SoftwareDocumentation

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

SoftwareDesignDocuments

SystemDocumenation

TestPlan

ProjectPlanning

End-UserDocumentation

SystemDocumentation

SoftwareTestDocumentation

SDPSoftwareDevelopment

Plan

ProjectDocumentationHigh-Level

RequirementsandDesignDocuments

UserManuals

SystemDocumentation

InstallationGuides

TestPlans

TestDocumentation

DetailedRequirementsandDesignDocuments

ERDiagramUMLDiagrams

FinalReport

Time

ProjectStart

ProjectFinish

HowtoTest/WhattoTest

CADDrawings

1.Planning

2.Testing

3.End-userDocumentation

4.Handover(Business people)

(Thepeoplethatshallactuallyusethesoftware)

TechnicalStuff

Howtouseit

Howtoinstallit

Proofthatyouhavetestedandthatthesoftwareworksasexpected

(stakeholders, thesoftwareteam;architects,UXdesigners,developers)

(QApeople)

(SuperUser/ITdep.)

WHAT

HOW

(EndUser)

ProjectPlanning SoftwareDevelopmentPlan(SDP)

ProjectM

anagem

ent(Ga

nttC

hart,etc.)

ProcessDocumentation

ProductDocumentation

SystemDocumentation

UserDocumentation

ProjectDocumentation

SoftwareProjectDocumentationCategories

ProjectPlan,GantChart,MeetingDocuments,Requirements&Designdocumentation,Emails,otherkindofWorkinDocuments,etc.

UserManual,Wikis,OnlineHelp,etc.

TechnicalDocumentationneeded inordertomaintainthesoftware,etc.

InstallationGuides

SoftwareProcessDocumentation

1. SoftwareDevelopmentPlan(SDP)2. SoftwareRequirements

Specifications(SRS)3. SoftwareDesignDocuments(SDD)4. SoftwareTestDocuments(STD)

SoftwareRequirements&DesignRequirements(WHAT):• WHAT thesystemshoulddo• DescribewhatthesystemshoulddowithWordsandFigures,etc.

• SRS – SoftwareRequirementsSpecificationSoftwareDesign(HOW):• HOW itshoulddoit• Examples:GUIDesign,UML,ERdiagram,CAD,etc.• SDD – SoftwareDesignDocumentManydontseparateSRSandSDDdocuments,butincludeeverythinginaRequirementsdocument.Inpractice,requirementsanddesignareinseparable.

TheSoftwareRequirementsDocumentSoftwareRequirmentsSpecifications(SRS)

• Thesoftwarerequirementsdocumentistheofficialstatementofwhatisrequiredofthesystemdevelopers.

• Shouldincludebothadefinitionofuserrequirementsandaspecificationofthesystemrequirements.

• ItisNOTadesigndocument.Asfaraspossible,itshouldsetofWHATthesystemshoulddoratherthanHOWitshoulddoit.

I.Sommerville,SoftwareEngineering:Pearson,2015.

TheStructureoftheSRSDocument

8

Chapter Description

Preface This should define the expected readership of the document and describe its version history, including a rationale for the creation ofa new version and a summary of the changes made in each version.

Introduction This should describe the need for the system. It should briefly describe the system’s functions and explain how it will work with othersystems. It should also describe how the system fits into the overall business or strategic objectives of the organizationcommissioning the software.

Glossary This should define the technical terms used in the document. You should not make assumptions about the experience or expertiseof the reader.

User requirements definition Here, you describe the services provided for the user. The nonfunctional system requirements should also be described in thissection. This description may use natural language, diagrams, or other notations that are understandable to customers. Product andprocess standards that must be followed should be specified.

Systemarchitecture This chapter should present a high-level overview of the anticipated system architecture, showing the distribution of functions acrosssystemmodules. Architectural components that are reused should be highlighted.

System requirements specification This should describe the functional and nonfunctional requirements in more detail. If necessary, further detail may also be added tothe nonfunctional requirements. Interfaces to other systems may be defined.

Systemmodels This might include graphical system models showing the relationships between the system components and the system and itsenvironment. Examples of possible models are object models, data-flowmodels, or semantic data models.

Systemevolution This should describe the fundamental assumptions on which the system is based, and any anticipated changes due to hardwareevolution, changing user needs, and so on. This section is useful for system designers as it may help them avoid design decisionsthat would constrain likely future changes to the system.

Appendices These should provide detailed, specific information that is related to the application being developed; for example, hardware anddatabase descriptions. Hardware requirements define the minimal and optimal configurations for the system. Databaserequirements define the logical organization of the data used by the systemand the relationships between data.

Index Several indexes to the document may be included. As well as a normal alphabetic index, there may be an index of diagrams, anindex of functions, and so on.

I.Sommerville,SoftwareEngineering:Pearson,2015.

SoftwareDocumentationRequirements

• ShouldactasacommunicationmediumbetweenmembersoftheDevelopmentTeam

• InformationrespositoryusedbyMaintenanceEngineers• InformationforManagementtohelpthemPlan,BudgetandSchedule theSoftwareDevelopmentProcess

• Someofthedocumentsshouldtellusershowtouseandadministerthesystem

• DocumentsforQualityControl,SystemCertification,etc.

=>SatisfyingtheserequirementsrequiresdifferenttypesofdocumentsfrominformalworkingdocumentsthroughprofessionallyproducedUserManuals

Ifthedocumentationisnotuseful– dontmakeit!!



• System/TechnicalDocumentation– ClassDiagrams– StateDiagrams– SequenceDiagrams– CodeComments

• UserDocumentation– UserManual– InstallationGuide–Wiki– OnlineDocumentationandHelp

SoftwareDocumentation• Forlargeprojects,itisusuallythecasethatdocumentationstartsbeinggeneratedwellbeforethedevelopmentprocessbegins

• Thesetofdocumentsthatyouhavetoproduceforanysystemdepends– onthecontractwiththeclientforthesystem(thecustomer)

– thetypeofsystembeingdeveloped– itsexpectedlifetime– thecompanyculture– thesizeofthecompanydevelopingthesystem– thedevelopmentschedule

Programmersdon'tdocumentL

ButtheyshouldJ!!!

SoftwareProjectDocumentation

DocumentationproducedduringasoftwareProjectcanbedividedinto2Categories:• ProcessDocumentation– Thesedocumentsrecordtheprocessofdevelopmentandmaintenance,e.g.,Plans,Schedules(e.g.,GanttCharts),etc.

• ProductDocumentation– Thesedocumentsdescribetheproductthatisbeingdeveloped.Canbedividedinto2subcategories:• SystemDocumentation

– Usedbyengineersdevelopingandmaintainingthesystem• UserDocumentation

– Usedbythepeoplethatisusingthesystem

15



Purpose:• ProcessDocumentationisproducedsothatthedevelopmentofthesystemcanbemanaged

• Itisanessentialcomponentofplan-drivenapproaches(e.g.,Waterfall)

• AgileApproaches:TheGoalistominimizetheamountofProcessDocumentation

Categories:1. Plans,estimatesandschedules.Thesearedocumentsproducedby

managerswhichareusedtopredictandtocontrolthesoftwareprocess.

2. Reports.Thesearedocumentswhichreporthowresourceswereusedduringtheprocessofdevelopment.

3. Standards.Thesearedocumentswhichsetouthowtheprocessistobeimplemented.Thesemaybedevelopedfromorganizational,nationalorinternationalstandards.

4. Workingpapers.Theseareoftentheprincipaltechnicalcommunicationdocumentsinaproject.Theyrecordtheideasandthoughtsoftheengineersworkingontheproject,areinterimversionsofproductdocumentation,describeimplementationstrategiesandsetoutproblemswhichhavebeenidentified.Theyoften,implicitly,recordtherationalefordesigndecisions.

5. E-mailmessages,wikis,etc.Theserecordthedetailsofeverydaycommunicationsbetweenmanagersanddevelopmentengineers.


SoftwareDevelopmentPlan(SDP)AnSDPnormallyincludethefollowingsections:1. Introduction:Thisbrieflydescribestheobjectivesoftheprojectandsetoutthe

constraints(e.g.,budget,time,etc.)thataffectsthemanagementoftheproject2. ProjectOrgianization (TeamDescription) Thissectiondescribeshowthe

developmentteamisorganized,thepeaople involvedandtheirrolesintheteam.SoftwareProcessModelDescription(Scrum,XP,Waterfall,...),etc.

3. RiskAnalysis4. HardwareandSoftwareResourceRequirements5. WorkBreakdown(WBS,WorkBreakdownStructure):Breakdowntheprojectin

intoactivitiesandidentifiesmilestones6. ProjectSchedule:Showsdependenciesbetweenactivities,theestimatedtime

requiredtoreacheachmilestone,allocationofpeopletoactivities.(5)and(6)istypicallydoneinaGanttChart(createdine.g.MicrosoftProject)

7. MonitoringandReportingMechanisms:DefinitionoftheManagementReportthatshouldbeproduced,whenthes shouldbeproduced,etc.

8. Toolsthatyouareusing

GanttChart

19

TestDocumentation

PlanningTests PerformTests DocumentTestResults

SoftwareTestPlan(STP)

SoftwareRequirementsSpecifications(SRS)SoftwareDesignDocument (SDD)

SoftwareTestDocumentation

(STD)

TestLogs

ThesedocumentswillbethefoundationforallTesting

- Functional&Non-FunctionalRequirements- User&SystemRequirements

ProductDocumentation

ProductDocumentationPurpose:• Describingthedeliveredsoftwareproduct• Unlikemostprocessdocumentation,ithasarelativelylonglife.

• ItmustEvolveinstepwiththeproductthatitdescribes.

• Productdocumentationincludes– Userdocumentation,whichtellsusershowtousethesoftwareproduct,

– SystemDocumentation,whichisprincipallyintendedformaintenanceengineers.

ProductDocumentationTypes&Readers

Tocaterforthesedifferentclassesofuseranddifferentlevelsofuserexpertise,severaldocuments(orperhapschaptersinasingledocument)shouldbedeliveredwiththesoftwaresystem.

ProductDocumentationUserDocumentation

UserDocumentation

• Usersofasystemarenotallthesame.• Theproducerofdocumentationmuststructureittocaterfor

differentusertasksanddifferentlevelsofexpertiseandexperience.

• Itisparticularlyimportanttodistinguishbetweenend-usersandsystemadministrators:

1. End-usersusethesoftwaretoassistwithsometask.– Thismaybeflyinganaircraft,managinginsurancepolicies,writinga

book,etc.Theywanttoknowhowthesoftwarecanhelpthem.Theyarenotinterestedincomputeroradministrationdetails.

2. Systemadministratorsareresponsibleformanagingthesoftwareusedbyend-users.– Thismayinvolveactingasanoperatorifthesystemisalarge

mainframesystem,asanetworkmanageristhesysteminvolvesanetworkofworkstationsorasatechnicalguruwhofixesend-userssoftwareproblemsandwholiaisesbetweenusersandthesoftwaresupplier.

UserDocumentationReaders

UserManual

Wiki

O.Widder.(2013).geek&poke.Available:http://geek-and-poke.com

ProductDocumentationSystemDocumentation

SystemDocumentation

30

SystemDocumentation

• Systemdocumentationincludesallofthedocumentsdescribingthesystemitselffromtherequirementsspecificationtothefinalacceptancetestplan.

• Documentsdescribingthedesign,implementationandtestingofasystemareessentialiftheprogramistobeunderstoodandmaintained.

• Likeuserdocumentation,itisimportantthatsystemdocumentationisstructured,withoverviewsleadingthereaderintomoreformalanddetaileddescriptionsofeachaspectofthesystem.

O.Widder.(2013).geek&poke.Available:http://geek-and-poke.com

CodeDocumentation

Forlargesystemsthataredeveloped toacustomer’sspecification, thesystemdocumentationshould include:1. Therequirements document.2. Adocumentdescribing thesystemarchitecture.3. Foreachprograminthesystem,adescriptionofthearchitectureofthatprogram.4. Foreachcomponent inthesystem,adescription ofitsfunctionalityandinterfaces.5. Programsourcecodelistings,whichshouldbecommentedwherethecomments

shouldexplaincomplexsectionsofcodeandprovidearationaleforthecodingmethodused.– Ifmeaningfulnamesareusedandagood,structuredprogrammingstyleisused,muchofthecodeshould

beselfdocumentingwithouttheneedforadditionalcomments.– Thisinformation isnownormallymaintainedelectronicallyratherthanonpaperwithselectedinformation

printedondemandfromreaders.

6. Validation documentsdescribinghoweachprogramisvalidatedandhowthevalidationinformation relatestotherequirements.– Thesemayberequiredforthequalityassuranceprocesses intheorganization.

7. ASystemMaintenanceGuide,whichdescribesknownproblemswiththesystem,describeswhichpartsof thesystemarehardwareandsoftwaredependentandwhichdescribeshowevolutionofthesystemhasbeentakenintoaccountinitsdesign

SystemDocumentation

UMLUseCaseDiagrams

ClassDiagrams

SequenceDiagrams

DatabaseERDiagramExample:

Summary

References

• I.Sommerville,SoftwareEngineering:Pearson,2015.• Wikipedia.(2013).ScrumDevelopment.Available:

http://en.wikipedia.org/wiki/Scrum_(development)• Wikipedia.(2013).AgileSoftwareDevelopment.Available:

http://en.wikipedia.org/wiki/Agile_software_development• CoreTrek.(2013).Scrumi etnøtteskall.Available:

http://www.coretrek.no/scrum-i-et-noetteskall/category642.html• S.Adams.Dilbert.Available:http://dilbert.com• O.Widder.(2013).Geek&Poke.Available:http://geek-and-

poke.com• B.Lund.(2013).Lunch.Available:http://www.lunchstriper.no,

http://www.dagbladet.no/tegneserie/lunch/

Hans-PetterHalvorsen,M.Sc.

UniversityCollegeofSoutheastNorwaywww.usn.no

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