Software Documentation Overview

SoftwareDocumentation
B.Lund.Lunch.Available:http://www.lunchstriper.no,http://www.dagbladet.no/tegneserie/lunch/
Hans-PetterHalvorsen,M.Sc.
End-User
Documentation
System
Documentation
STD
UserGuides
Installation
Guides
Deployment
SDP
Maintenance
SoftwareDevelopment
Plan
ProjectPlanning
Testing
SoftwareTestDocumentation
TestPlan
Test
Documentation
Planning
GanttChart
YourSoftware
withDocumentation
Requirements
Analysis
SRS
Implementation
SoftwareRequirements
Specifications
Code
SystemDocumenation
Design
SDD
SoftwareDesignDocuments
withERDiagram,UMLDiagrams,CADDrawings
ProjectDocumentation
1.Planning
(stakeholders, the
softwareteam;
architects,UX
designers,
developers)
Time
ProjectManagement(GanttChart,etc.)
ProjectStart
ProjectFinish
2.Testing
(QApeople)
3.End-user
Documentation
ProjectPlanning
SoftwareDevelopmentPlan(SDP)
High-Level
Requirementsand
DesignDocuments
WHAT
Detailed
Requirementsand
DesignDocuments
ERDiagram
UMLDiagrams
CADDrawings
TestPlans
TestDocumentation
HowtoTest/
WhattoTest
Proofthatyou havetested
andthatthesoftwareworks
asexpected
System
Documentation
TechnicalStuff
InstallationGuides
Howtoinstallit
(Thepeoplethat
shallactuallyuse
thesoftware)
UserManuals
4.Handover
FinalReport
(Business people)
HOW
(SuperUser/ITdep.)
Howtouseit
(EndUser)
SoftwareProjectDocumentationCategories
Project
Documentation
Process
Documentation
ProjectPlan,GantChart,MeetingDocuments,
Requirements&Designdocumentation,
Emails,otherkindof WorkinDocuments, etc.
System
Documentation
TechnicalDocumentation needed in
ordertomaintainthesoftware,etc.
Product
Documentation
Installation
Guides
User
Documentation
UserManual,Wikis,Online
Help, etc.
SoftwareProcessDocumentation
1. SoftwareDevelopmentPlan(SDP)
2. SoftwareRequirements
Specifications(SRS)
3. SoftwareDesignDocuments(SDD)
4. SoftwareTestDocuments(STD)
SoftwareRequirements&Design
Requirements(WHAT):
• WHAT thesystemshoulddo
• DescribewhatthesystemshoulddowithWordsand
Figures,etc.
• SRS – SoftwareRequirementsSpecification
SoftwareDesign(HOW):
• HOW itshoulddoit
• Examples:GUIDesign,UML,ERdiagram,CAD,etc.
• SDD – SoftwareDesignDocument
ManydontseparateSRSandSDDdocuments,butincludeeverythingina
Requirementsdocument.
Inpractice,requirementsanddesignareinseparable.
TheSoftwareRequirementsDocument
SoftwareRequirmentsSpecifications(SRS)
• Thesoftwarerequirementsdocumentisthe
officialstatementofwhatisrequiredofthe
systemdevelopers.
• Shouldincludebothadefinitionofuser
requirementsandaspecificationofthe
systemrequirements.
• ItisNOTadesigndocument.Asfaras
possible,itshouldsetofWHATthesystem
shoulddoratherthanHOWitshoulddoit.
I.Sommerville,SoftwareEngineering:Pearson,2015. TheStructureoftheSRSDocument
Chapter
Description
Preface
This should define the expected readership of the document and describe its version history, including a rationale for the creation of
a 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 other
systems. It should also describe how the system fits into the overall business or strategic objectives of the organization
commissioning the software.
Glossary
This should define the technical terms used in the document. You should not make assumptions about the experience or expertise
of the reader.
User requirements definition
Here, you describe the services provided for the user. The nonfunctional system requirements should also be described in this
section. This description may use natural language, diagrams, or other notations that are understandable to customers. Product and
process standards that must be followed should be specified.
System architecture
This chapter should present a high-level overview of the anticipated system architecture, showing the distribution of functions across
system modules. 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 to
the nonfunctional requirements. Interfaces to other systems may be defined.
System models
This might include graphical system models showing the relationships between the system components and the system and its
environment. Examples of possible models are object models, data-flow models, or semantic data models.
System evolution
This should describe the fundamental assumptions on which the system is based, and any anticipated changes due to hardware
evolution, changing user needs, and so on. This section is useful for system designers as it may help them avoid design decisions
that 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 and
database descriptions. Hardware requirements define the minimal and optimal configurations for the system. Database
requirements define the logical organization of the data used by the system and 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, an
index of functions, and so on.
8
I.Sommerville,SoftwareEngineering:Pearson,2015. SoftwareDocumentationRequirements
• Shouldactasacommunicationmediumbetween
membersoftheDevelopmentTeam
• InformationrespositoryusedbyMaintenanceEngineers
• InformationforManagementtohelpthemPlan,Budget
andSchedule theSoftwareDevelopmentProcess
• Someofthedocumentsshouldtellusershowtouseand
administerthesystem
• DocumentsforQualityControl,SystemCertification,etc.
=>Satisfyingtheserequirementsrequiresdifferenttypesof
documentsfrominformalworkingdocumentsthrough
professionallyproducedUserManuals
SoftwareDocumentation
Ifthedocumentationisnotuseful– dontmakeit!!
SoftwareDocumentation
• System/TechnicalDocumentation
– ClassDiagrams
– StateDiagrams
– SequenceDiagrams
– CodeComments
• UserDocumentation
– UserManual
– InstallationGuide
– Wiki
– OnlineDocumentationandHelp
SoftwareDocumentation
• Forlargeprojects,itisusuallythecasethat
documentationstartsbeinggeneratedwellbeforethe
developmentprocessbegins
• Thesetofdocumentsthatyouhavetoproduceforany
systemdepends
– onthecontractwiththeclientforthesystem(the
customer)
– thetypeofsystembeingdeveloped
– itsexpectedlifetime
– thecompanyculture
– thesizeofthecompanydevelopingthesystem
– thedevelopmentschedule
Programmersdon'tdocumentL
ButtheyshouldJ!!!
SoftwareProjectDocumentation
DocumentationproducedduringasoftwareProject
canbedividedinto2Categories:
• ProcessDocumentation
– Thesedocumentsrecordtheprocessofdevelopment
andmaintenance,e.g.,Plans,Schedules(e.g.,Gantt
Charts),etc.
• ProductDocumentation
– Thesedocumentsdescribetheproductthatisbeing
developed.Canbedividedinto2subcategories:
• SystemDocumentation
– Usedbyengineersdevelopingandmaintainingthesystem
• UserDocumentation
– Usedbythepeoplethatisusingthesystem
ProcessDocumentation
15
ProcessDocumentation
Purpose:
• ProcessDocumentationisproducedsothat
thedevelopmentofthesystemcanbe
managed
• Itisanessentialcomponentofplan-driven
approaches(e.g.,Waterfall)
• AgileApproaches:TheGoalistominimizethe
amountofProcessDocumentation
ProcessDocumentation
Categories:
1. Plans,estimatesandschedules.Thesearedocumentsproducedby
managerswhichareusedtopredictandtocontrolthesoftware
process.
2. Reports.Thesearedocumentswhichreporthowresourceswereused
duringtheprocessofdevelopment.
3. Standards.Thesearedocumentswhichsetouthowtheprocessisto
beimplemented.Thesemaybedevelopedfromorganizational,
nationalorinternationalstandards.
4. Workingpapers.Theseareoftentheprincipaltechnical
communicationdocumentsinaproject.Theyrecordtheideasand
thoughtsoftheengineersworkingontheproject,areinterimversions
ofproductdocumentation,describeimplementationstrategiesandset
outproblemswhichhavebeenidentified.Theyoften,implicitly,record
therationalefordesigndecisions.
5. E-mailmessages,wikis,etc.Theserecordthedetailsofeveryday
communicationsbetweenmanagersanddevelopmentengineers.
SoftwareDevelopmentPlan(SDP)
AnSDPnormallyincludethefollowingsections:
1. Introduction:Thisbrieflydescribestheobjectivesoftheprojectandsetoutthe
constraints(e.g.,budget,time,etc.)thataffectsthemanagementoftheproject
2. ProjectOrgianization (TeamDescription) Thissectiondescribeshowthe
developmentteamisorganized,thepeaople involvedandtheirrolesinthe
team.SoftwareProcessModelDescription(Scrum,XP,Waterfall,...),etc.
3. RiskAnalysis
4. HardwareandSoftwareResourceRequirements
5. WorkBreakdown(WBS,WorkBreakdownStructure):Breakdowntheprojectin
intoactivitiesandidentifiesmilestones
6. ProjectSchedule:Showsdependenciesbetweenactivities,theestimatedtime
requiredtoreacheachmilestone,allocationofpeopletoactivities.(5)and(6)is
typicallydoneinaGanttChart(createdine.g.MicrosoftProject)
7. MonitoringandReportingMechanisms:DefinitionoftheManagementReport
thatshouldbeproduced,whenthes shouldbeproduced,etc.
8. Toolsthatyouareusing
GanttChart
19
TestDocumentation
SoftwareTestPlan(STP)
TestLogs
PlanningTests
PerformTests
Document
TestResults
SoftwareTest
Documentation
(STD)
SoftwareDesignDocument (SDD)
SoftwareRequirementsSpecifications(SRS)
- Functional&Non-FunctionalRequirements
- User&SystemRequirements
ThesedocumentswillbethefoundationforallTesting
ProductDocumentation
ProductDocumentation
Purpose:
• Describingthedeliveredsoftwareproduct
• Unlikemostprocessdocumentation,ithasa
relativelylonglife.
• ItmustEvolveinstepwiththeproductthatit
describes.
• Productdocumentationincludes
– Userdocumentation,whichtellsusershowtousethe
softwareproduct,
– SystemDocumentation,whichisprincipallyintendedfor
maintenanceengineers.
ProductDocumentationTypes&Readers
Tocaterforthesedifferentclassesofuseranddifferentlevelsofuserexpertise,
severaldocuments(orperhapschaptersinasingledocument)shouldbedelivered
withthesoftwaresystem.
ProductDocumentation
UserDocumentation
UserDocumentation
UserDocumentationReaders
• Usersofasystemarenotallthesame.
• Theproducerofdocumentationmuststructureittocaterfor
differentusertasksanddifferentlevelsofexpertiseand
experience.
• Itisparticularlyimportanttodistinguishbetweenend-usersand
systemadministrators:
1. End-usersusethesoftwaretoassistwithsometask.
–
Thismaybeflyinganaircraft,managinginsurancepolicies,writinga
book,etc.Theywanttoknowhowthesoftwarecanhelpthem.
Theyarenotinterestedincomputeroradministrationdetails.
2. Systemadministratorsareresponsibleformanagingthe
softwareusedbyend-users.
–
Thismayinvolveactingasanoperatorifthesystemisalarge
mainframesystem,asanetworkmanageristhesysteminvolvesa
networkofworkstationsorasatechnicalguruwhofixesend-users
softwareproblemsandwholiaisesbetweenusersandthesoftware
supplier.
UserManual
Wiki
O.Widder.(2013).geek&poke.Available:http://geek-and-poke.com
ProductDocumentation
SystemDocumentation
System
Documentation
30
SystemDocumentation
• Systemdocumentationincludesallofthedocuments
describingthesystemitselffromtherequirements
specificationtothefinalacceptancetestplan.
• Documentsdescribingthedesign,implementation
andtestingofasystemareessentialiftheprogramis
tobeunderstoodandmaintained.
• Likeuserdocumentation,itisimportantthatsystem
documentationisstructured,withoverviewsleading
thereaderintomoreformalanddetaileddescriptions
ofeachaspectofthesystem.
CodeDocumentation
O.Widder.(2013).geek&poke.Available:http://geek-and-poke.com
SystemDocumentation
Forlargesystemsthataredeveloped toacustomer’sspecification, thesystem
documentation should include:
1.
Therequirements document.
2.
Adocumentdescribing thesystemarchitecture.
3.
Foreachprograminthesystem,adescription ofthearchitectureofthatprogram.
4.
Foreachcomponent inthesystem,adescription ofitsfunctionality andinterfaces.
5.
Programsourcecodelistings, whichshould becommentedwherethecomments
should explaincomplexsectionsofcodeandprovidearationaleforthecoding method
used.
–
–
6.
Validation documents describing howeachprogramisvalidatedandhowthevalidation
information relatestotherequirements.
–
7.
Ifmeaningfulnamesareusedandagood,structuredprogrammingstyleisused, muchofthecodeshould
beselfdocumentingwithouttheneedforadditionalcomments.
Thisinformation isnownormally maintainedelectronicallyratherthanonpaperwithselectedinformation
printedondemandfromreaders.
Thesemayberequiredforthequalityassuranceprocesses intheorganization.
ASystemMaintenanceGuide,whichdescribesknown problems withthesystem,
describeswhichpartsof thesystemarehardwareandsoftwaredependent andwhich
describeshowevolution ofthesystemhasbeentakenintoaccountinitsdesign
UseCaseDiagrams
UML
ClassDiagrams
Sequence Diagrams
DatabaseERDiagram
Example:
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-andpoke.com
• B.Lund.(2013).Lunch.Available:http://www.lunchstriper.no,
http://www.dagbladet.no/tegneserie/lunch/
Hans-PetterHalvorsen,M.Sc.
UniversityCollegeofSoutheastNorway
www.usn.no
E-mail:hans.p.halvorsen@hit.no
Blog:http://home.hit.no/~hansha/