Document Management in SW Projects – Recommendations and Hints

1. www.luxoft.com
Documentation management
in SW Projects

2. www.luxoft.com
Three “little stories”
 Story 1
- Mentor: “To be able to do something useful you have to know the basis about our project”
- Engineer: “Where can I read about it?”
 Story 2
- Customer: “I don’t accept it”
- Team: “But this is what we have agreed”
- Customer: “I don’t think so.”
 Story 3
- Team A: “We will send you those parameters, you just have to save them”
- Team B: “Which parameters?”
- Team A: “The one I have described you yesterday”

3. www.luxoft.com
Content
1. Requirements
2. Architecture
3. Documentation development process
4. Quality
5. Tooling

4. www.luxoft.com
Requirements

5. www.luxoft.com
Requirements mess :)

6. www.luxoft.com
Requirements model
Customer (“Wishes”) Supplier (“Specifications”)
End user
Functional
C-RS S-RSNon-Functional
Other
Engineering
Functional
C-TRS S-TRSNon-Functional
Other
Managerial
Organizational
C-PRS S-PRSFinancial
Other

7. www.luxoft.com
Requirements elaboration
 Customer requirements are fragmented and
don’t match needs of supplier
 Supplier requirements is an elaboration or
merge of corresponding supplier and
customer requirements
 S-TRS is the main “source of truth” for
“What has to be done?” question
 S-PRS is the main “source of truth” for
“How project has to be done?” question
C-PRS
C-RS
C-TRS
S-PRS
S-RS
S-TRS
Architecture
Design
Code
Customer Supplier

8. www.luxoft.com
Requirements model – typical names
Group Content type Customer Supplier
End user
Functional CRS TRS
Non-Functional CRS TRS
Other Not tracked Not tracked
Engineering
Functional Specifications TRS
Non-Functional Specifications TRS
Other Not tracked Not tracked
Managerial
Organizational PMP S-PRS
Financial Contract template, SOW template Contract, SOW
Other Not tracked Contract, SOW, Not tracked

9. www.luxoft.com
End user requirements and elements examples
Requirements that describe cooperation
between system and actual user (person).
 Can describe system not precisely
 Can be verified by end user when system is
running
 Not related to the internal structure of the
system – describe system as a “black box”
 Functional
- Use cases
- User stories
- User Features
 Non-Functional
- System Responsiveness
- System Up-time
- System Recoverability
 Hardware
- Type
- Size, Weight

10. www.luxoft.com
Engineering requirements and elements examples
Requirements that clarify end user
requirements and describe system with the
level of technical details necessary to develop
system.
 Maximize precision level of system
description
 It might be possible to verify them by end
user
 Can describe any internal structure,
communication, protocol, rules, etc.
 Functional
- Use cases specifications
- Protocols definition
 Non-Functional
- Modules recoverability
- Timing requirements
 HW
- HW specifications

11. www.luxoft.com
Managerial requirements and elements examples
Requirements that describe why, when and
how project/product will be done.
 Can be related to any managerial aspect
 Typically appear first, get finalized last
 Organizational
- Milestones
- Processes (PMP, CMP)
- Team
- Risks, Assumptions, Dependencies
- Communication
- Quality
 Financial
- Payments
- Scope

12. www.luxoft.com
Requirements sources
End-user
 Customer input
 Business analysis
 End-user feedback
 Testers feedback
 Experience
Engineering
 Requirements analysis
 Requirements elaboration
 Architecture definition
 Design definition
 System analysis
 Experience
Managerial
 Team capabilities
 Customer negotiations
 Requirements analysis
 Risks analysis
 Experience

13. www.luxoft.com
Architecture

14. www.luxoft.com
Typical “Architecture”

15. www.luxoft.com
Architecture enterprise model (Zachman framework)

16. www.luxoft.com
Architecture model (Simplified 1)
What How Where Who When Why
Executive Scope
High-level
processes
Location R&R, Team Milestones
Business goal,
Payments
Managerial
requirements
Product
End-user
Features
Use cases,
Non-functional
System
deployment
Users
Non-functional
requirements
Business proc.
analysis
End-user requirements
Architect
Technical
features
Sequences
SW
Deployment
Domains Timing Traces SW Architecture
Development Module features
Sequences
Algorithms
SW
Deployment
Components
Classes
Timings Traces High-Level Design
Team Team tooling
Managerial
requirements

17. www.luxoft.com
Architecture model (simplified 2)
Managerial requirements
End-user requirements
Engineering requirements
System/SW Architecture
^ High-Level Design

18. www.luxoft.com
Documentation elaboration
 Architecture is an elaboration of S-TRS
 Customer expectations related to
implementation are treated as C-TRS
- This allows to simplify actual development
 Design is an elaboration and a part of
architecture
 Architecture is the main “source of truth”
for “How it has to work?” question
C-PRS
C-RS
C-TRS
Architecture
Design
Code
S-PRS
S-RS
S-TRS
Architecture
Design
Code
Customer Supplier

19. www.luxoft.com
SW Architecture and elements example
Document that describes decisions taken to
define system boundaries, internal structure
and rules
 Is derived from requirements
 Defines sub-systems/modules
(responsibilities, boundaries)
 Defines communication principles between
sub-systems/modules
 Considers modules as black-box
 Responsibilities
 Decisions
 Logical view
- System view, System level architecture
- Functional domain breakdown
 Development view
- Code development guidelines
- Integration strategy, Integrated libraries
 Physical view
- Partitioning. Memory limits, CPU limits
- IPC, Processes
 Conventions

20. www.luxoft.com
High-Level design and elements example
Document that describes decisions taken to
define sub-system/module internal structure
and rules
 Defines details of communications between
modules, subsystems
 Defines details of sub-system
 Responsibilities
 Decisions
 High level design
- System view
- Environment (Outgoing, Incoming)
- Breakdown (components, interfaces, internal
dependencies)
- Deployment (Binaries, Threads)
- Testing strategy
 Detailed view
- Components, interfaces, etc.
- Diagrams

21. www.luxoft.com
Architecture sources
System/SW Architecture
 Engineering requirements
 End-user requirements
 Managerial requirements
 Technical Limitations
 3rd party modules
 Legacy code
 Experience
High-Level design
 System/SW Architecture
 Engineering requirements
 Experience

22. www.luxoft.com
Documentation development process

23. www.luxoft.com
Development process – V-Model - expectation

24. www.luxoft.com
Development process important notes
“V” model is always used, but usage might vary.
 Iterative development (like SCRUM) have simplified “V” on every
iteration
 Change request processing – is a “V” for a single feature

25. www.luxoft.com
Development & Documentation process – typical reality
• Clarifications
• Supplier requirements
development
(fragments)
Customer
requirements
analysis
• More clarifications
• Major architecture
decisions specification
Architecture
development • More clarifications
• Design documentation
(fragments)
• First coding
(prototyping)
Design
development
• More clarifications
• Some updates to
design
• Coding
• Testing
Development
• Test cases definition
• System testing
• More clarifications
• Testers feedback
System testing

26. www.luxoft.com
Typical reality problems
• Only fragments of clarified requirements are documented
Customer requirements analysis
• Requirements are not updated after further clarifications
• Not all architecture decisions are documented
• Reasons for decisions are not documented
Architecture development
• Requirements are not updated after further clarifications
• Architecture is not updated after further clarifications
• Only fragments of design are documented
• Prototyping is considered by management as first results, rather than Proof-Of-Concept
Design development
• Requirements, Architecture, Design are not updated after further clarifications
• Requirements, Architecture, Design are not updated after coding and testing
Development
• Requirements, Architecture, Design are not updated after further clarifications or feedback
• Decisions on bug-fixing are taken quickly, locally, without checking impact on the whole system
Testing

27. www.luxoft.com
Important Consequences
No baseline
Working on different
requirements for different
release
Mismatch between
different parts of
documentation
Outdated documentation

28. www.luxoft.com
Reasons
It is hard to
formulate
decision shortly
• Engineers try to avoid
this
Documentation is
separated from
the main process
• It becomes “additional
effort”
Time pressure
• Short-term
perspective focus
(quick-fix, quick-
solution)
• “Additional effort” is
not worth it
“Team is aware of
all decisions”
• “It’s easier and faster
to tell than to write”
• “Documentation is
outdated anyway”

29. www.luxoft.com
Tips to improve
Define required
documentation details
•I won’t do more that absolutely
required anyway
•You will do what is absolutely
required anyway
Simplify documentation
development
•Use advanced tooling
•Make tutorials on tooling usage
•Show how to use the tool yourself –
during meetings, talks
Make documentation part of
the process
•Integrate process with tool to avoid
“additional effort” for documentation
•Document decisions, agreements
immediately by tool
•Ask for decisions in written form

30. www.luxoft.com
Quality

31. www.luxoft.com
Product quality definition (by standard)
ISO
9126
Functionality
• Suitability
• Accuracy
• Interoperability
• Security
• Functionality
compliance
Reliability
• Maturity
• Fault tolerance
• Recoverability
• Reliability
compliance
Usability
• Understandability
• Learnability
• Operability
• Attractiveness
• Usability
compliance
Efficiency
• Time behaviour
• Resource utilization
• Efficiency
compliance
Maintainability
• Analyzability
• Changeability
• Stability
• Testability
• Maintainability
compliance
Portability
• Adaptability
• Installability
• Co-existence
• Replaceability
• Portability
compliance
Product is of good quality if
 I like it, because it
(usability)
 satisfies my needs by
(functionality)
 helping me to reach my goals easier by
(efficiency)
 doing what I want, how I want
(functionality, efficiency)
 with a quality I want and
(functionality, efficiency)
 does have no problems while doing this
(reliability)

32. www.luxoft.com
How to ensure good quality
Each quality requirement shall be met
- Before product development
 Choose correct development model
- During product definition
 Make correct business analysis
- During product development
 Develop what was defined
 Ensure mature development process
- After product development
 Verify result against requirements
Quality related roles
 Business analytic
 Requirements manager
 Architect
 Technical lead
 Quality engineer
 Developer

33. www.luxoft.com
Questions that are hard to answer
When starting project
 Have we processed all customer r. and
developed corresponding supplier r.?
 Have we processed all end-user r. and
developed corresponding engineering r.?
 Have we processed all engineering r. and
made corresponding architectural decisions,
sub-systems, modules?
 Have we processed all architectural
decisions and made corresponding design
decisions, interfaces, classes, sequences?
When processing any change
 What will be the impact if this module, class, etc. is
changed?
- What might be broken?
- What shall be tested?
 What will be the impact if this module will be
moved/changed?
- Which end-user functionality will be affected?
- Which other modules, teams will be affected?
- How much time will it take?
- How much will this cost?

34. www.luxoft.com
Traceability
Traceability is a bi-directional linkage
between elements of the documentation
 Allows to answer important questions
(prev. slide) by making coverage analysis
 Answers questions “derived from”,
“required because”, “required by”
 Allows to analyze impacts in case of
change of an item
 Allows to automate reporting
Managerial
requirements
End-user
requirements
Engineering
requirements
Managerial
requirements
End-user
requirements
Engineering
requirements
Architecture
High-Level
Design
Code
Customer Supplier

35. www.luxoft.com
Tooling

36. www.luxoft.com
Typical tooling
Documents
(Word, PDF, etc.)
• Easy to start
• Hard to compare
• Hard to make
version control
• Hard to make
linkage between
documents
• Developers don’t
like
Wikipedia style
(ex.: Confluence)
• Harder to start
• Easy to compare
• Easy to make
version control
• Easy to make
linkage between
documents, but
hard to track
them
• Developers
might like
GIT
documentation
• Harder to start
• Easy to compare
• Easy to make
version control
• Harder to make
linkage between
documents, hard
to track them
• Developers like
Special tools
• Harder to start
• Easy to compare
• Easy to make
version control
• Easier to make
linkage between
documents, easy
to track them
• Developers don’t
like
• Costs
Special formats
• Hard to start
• Easy to compare
• Easy to make
version control
• Easier to make
linkage between
documents, easy
to track them
• Developers
might like
• Support
generation of
any document

37. www.luxoft.com
THANK YOU