Documentation and Agile Methodology

112 Pages·2013·0.89 MB·English

by  Islam Jan

DEPARTMENT OF INFORMATICS AND MEDIA, UPPSALA
UNIVERSITY
Documentation and Agile Methodology
Islam Jan and Shams Tabrez
MasterinInformationSystemsSciences
Supervisor: JonasSjöström
December11,2013
(cid:13)c IslamJanandShamsTabrez,2013
Abstract
Computerscienceingeneralandsoftwareengineeringinspecificischangingveryfast. Software
engineers are constantly using more innovative and more efficient ways to develop new software
than in the past. This continuous evolution of software development methodologies has a great
impact on both the software developed and the environment that the developers work-in. Agile
software developmentmethodologies areused to overcomemany issues inthe softwaredevelop-
ment processes. One of the issues which still exists and needs to be addressed is the preparation
ofproperdocumentationalongwiththesoftware. Theworkpresentedinthisdissertationfocuses
onsoftwaredocumentation.
Theworkstartsbyathoroughliteraturereviewwhichfocusesondifferentaspectsofsoftware
documentationanddifferentagilemethodologies. Thethesisfocusesonfindingoutthechallenges
thatthedevelopersfacesduringtheirdevelopmentprocess. Twomajorquestionsaddressedinthe
thesis. Firstoneistofindthemotivationtodocumentinagileenvirionment,whihisbasedonthe
hypothesisthattheredoexistamotivation. Thesecondquestionisthathowshoulddocumentation
beproducedsuchthatwecouldavoidmaximumpossiblepotentialproblems. Thesequestionsare
addressed with the help of different perspectives of the stockholders (i.e. developers and users)
andtheexistingmethodsfordocumentation.
Aquestionnairewasdevelopedbasedontheninecategoriesofdocumentation,likeuserdocu-
mentsandsystemdocumentsetc.. Itincludeddifferentquestionsrelatedtothetypesofdocuments
created in software development processes, the software development stage at which the docu-
ments are created and the importance of the documents. Questions from this questionnaire are
thenpostedonagilespecificdiscussionforums. Wheremanyexperiencedandfreshpractitioners
participated in the discussion. We had a detailed discussion on every component of documenta-
tionandproblemswereidentifiedbythepractitioners. Thequestionnairewasalsosenttodifferent
companiespracticingagilemethodology. wereceivedabout14responsesasitwasdetailedques-
tionnairewithabout34questions.
The responses of the discussion forum and survey are then analyzed and conclusions were
drawn. The conclusions include that all the participants consider software documentation very
important to the success of a software development project. the question of motivation is an-
sweredfromtheliteratureandopinionswereceivedfromexperiencedpractitioners. Whileseven
factorareidentifiedthataffectyourdocumentation,tohelpsolvethequestionofhowshoulddoc-
umentationbedone.
i
ii
Acknowledgment
First of all, we would like to thank Allah Almighty because without his blessings, we could not
havefulfilledthisdifficulttask.
We are thankful to our supervisor Jonas Sjöström1 because without his continuous guidance,
supportandhelpitwouldhavetakenalongtimetocomplete.
We would also like to thank the participants in the questionnaire, who has willingly shared
theirprecioustimeduringourresearchwork.
Atthisstage, wearealsothankfultoourparents, brothersandsistersforbeingpatiencewith
usandofferingwordsofencouragementthroughoutourthesiswork.
WewouldalsoliketothankDr. ArifUrRahman2 forgivingvaluablecommentsonthework
andprovidingtechnicalassistanceinwritingthethesisdocumentinLatex.
ISLAM JAN & SHAMS TABREZ
1JonasSjöström,SeniorLecturer,DepartmentofInformaticsandMedia,UppsalaUniversity,Sweden.
[email protected]
2DepartmentofInformaticsEngineering,FacultyofEngineering,UniversityofPorto,Portugal.
[email protected]
iii
iv
“Documentationisthecastoroilofprogramming.
Managersthinkitisgoodforprogrammersandprogrammershateit!”
GeraldWeinberg
v
vi
Contents
Abstract i
Acknowledgment iii
Abbreviations xv
1 Background 1
1.1 RelatedWork . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 ResearchQuestionandPurposeoftheStudy . . . . . . . . . . . . . . . . . . . . 3
1.3 DissertationOutline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 ResearchMethodology 7
2.1 Definitionofresearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 ResearchMethodology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.1 Exploratoryresearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.2 EmpiricalResearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2.3 ConstructiveResearch . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 QualitativeAnalysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.1 LiteratureReview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.3.2 EmpiricalStudy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.3 FormulateQuestionnaire . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3.4 StructuralInterview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.3.5 CommentsorOpinionsthroughdiscussionforum . . . . . . . . . . . . . 11
2.3.6 IdentifyDocumentationComponents . . . . . . . . . . . . . . . . . . . 11
2.4 DesignResearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.5 ReliabilityandValidityofResearch . . . . . . . . . . . . . . . . . . . . . . . . 12
2.6 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3 DocumentationIntroduction 15
3.1 DocumentationandAgile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 ProcessDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3.2.1 Plans,estimatesandschedules . . . . . . . . . . . . . . . . . . . . . . . 18
3.2.2 Reports,memosandelectronicmessages . . . . . . . . . . . . . . . . . 18
3.2.3 Workingpapers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.2.4 Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3 ProductDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.1 UserDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
3.3.2 Systemdocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
vii
viii CONTENTS
4 AgileSoftwareDevelopment 25
4.1 AgileSoftwaredevelopment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.2 Scrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.2.1 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.2.2 Meetings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.2.3 Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.3 ExtremeProgramming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
4.4 Featuredrivendevelopment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5 LiteratureDiscussion 33
5.1 LiteratureDiscussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6 DataAnalysisandInterpretation 39
6.1 DataNeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.2 DataAnalysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.3 DocumentationComponents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.3.1 UserDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.3.2 DesignDecision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
6.3.3 Visionstatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.3.4 ProjectOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.3.5 RequirementsDocument . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.3.6 SupportDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.3.7 SystemDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.3.8 OperationDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . 69
6.3.9 ContractModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.4 InterpretationofData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
6.4.1 TypeofProduct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
6.4.2 SizeoftheProject . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.4.3 Theenvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.4.4 ExperienceoftheTeam . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.4.5 CustomerRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.4.6 TypeandLevelofUsers . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6.4.7 ToolsUsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.5 Standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7 DiscussionandConclusion 79
7.1 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.2 Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
A Questionnaire 85
A.1 UserDocuments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
A.2 DesignDecision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
A.3 VisionStatement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
A.4 ProjectOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
A.5 RequirementsDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
A.6 SupportDocuments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
A.7 SystemDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
A.8 OperationsDocumentations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
A.9 ContractModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89