Software Documentation

Transcription

1 Software Documentation Quiz with Explainations Hans-Petter Halvorsen, M.Sc.

2 Questions 1. List 4 important Process Documents 2. What are the main Software Documentation Categories? 3. What is SRS? 4. What should the Software Development Plan (SDP) include? 5. What is the Purpose with Product Documentation? 6. What is the 2 main Categories of Users? 7. Give Examples of detailed Technical Design Diagrams? 8. Give an Overview of different types of Readers and what kind of Documents they read 9. What should the System Documentation include? 10. Give an Overview of different Types of Test Documentation

3 List 4 important Process Documents

4 Software Process Documentation 1. Software Development Plan (SDP) 2. Software Requirements Specifications (SRS) 3. Software Design Documents (SDD) 4. Software Test Documents (STD)

5 What are the main Software Documentation Categories?

6 Software Project Documentation Categories Project Documentation Process Documentation Project Plan, Gant Chart, Meeting Documents, Requirements & Design documentation, s, other kind of Workin Documents, etc. Product Documentation System Documentation Technical Documentation needed in order to maintain the software, etc. Installation Guides User Documentation User Manual, Wikis, Online Help, etc.

7 Software Project Documentation Documentation produced during a software Project can be divided into 2 Categories: Process Documentation These documents record the process of development and maintenance, e.g., Plans, Schedules (e.g., Gantt Charts), etc. Product Documentation These documents describe the product that is being developed. Can be divided into 2 sub categories: System Documentation Used by engineers developing and maintaining the system User Documentation Used by the people that is using the system 7

8 What is SRS?

9 The Software Requirements Document Software Requirements Specifications (SRS) The software requirements document is the official statement of what is required of the system developers. Should include both a definition of user requirements and a specification of the system requirements. It is NOT a design document. As far as possible, it should set of WHAT the system should do rather than HOW it should do it. I. Sommerville, Software Engineering: Pearson,

10 The Structure of the SRS Document Example 1 Chapter Preface Description This should define the ex pec ted 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 ex pl ai n how it will work with other systems. It should also describe how the system fits into the overall business or strategic objectives of theorganizationcommissioning 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 hel p 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 I. Sommerville, Software Engineering: Pearson, Several indexes to the document may be included. As well as a normal al phabeti c index, there may be an index of diagrams, an index of functions, and so on. 10

11 The Structure of the SRS Document Example 2 A. System Overview (brief description of what the softare system will do) B. Technical Requirements (Functional requirement, Nonfunctional requirements, User-interface specification, User task flow, Input/output and other data specifications, Interface specifications to other systems) C. Acceptance Criteria/Interaction Scenarios D. Validation/Verification E. Requirements Considerations (Assumption made about the software, End users, Existing systems, Environment, Limitations) F. Other Information... Essentials of Software Engineering, Frank Tsui; Orlando Karam; Barbara Bernal, 3 ed., Jones & Bartlett Learning

12 What should the Software Development Plan (SDP) include?

13 Software Development Plan (SDP) A Software Development Plan (SDP) is all about the Internal Communication within the Development Team and how it Communicates with rest of the Organization, the Customers, etc.

14 Software Development Plan (SDP) A Project Plan normally include the following sections: 1. Introduction: This briefly describes the objectives of the project and set out the constraints (e.g., budget, time, etc.) that affects the management of the project 2. Project Orgianization (Team Description) This section describes how the development team is organized, the peaople involved and their roles in the team. Software Process Model Description (Scrum, XP, Waterfall,...), etc. 3. Risk Analysis 4. Hardware and Software Resource Requirements Example 1 5. Work Breakdown (WBS, Work Breakdown Structure): Break down the project in into activities and identifies milestones 6. Project Schedule: Shows dependencies between activities, the estimated time required to reach each milestone, allocation of people to activities. (5) and (6) is typically done in a Gantt Chart (created in e.g. Microsoft Project) 7. Monitoring and Reporting Mechanisms: Definition of the Management Report that should be produced, when thes should be produced, etc. 8. Tools that you are using I. Sommerville, Software Engineering: Pearson,

15 Here is another Example of SDP: Software Development Plan (SDP) A. Product Description B. Team Description C. Software Process Model Description D. Project Definition E. Project Organization F. Validation Plan G. Configuration/Version Control H. Tools For more details, see Essentials of Software Engineering, Frank Tsui; Orlando Karam; Barbara Bernal, 3 ed., Jones & Bartlett Learning Example 2 Depending on the size and complexity of the project, the plan itself may take several hours to several days or weeks to develop

16 What is the Purpose with Product Documentation?

17 Product Documentation Purpose: Describing the delivered software product Unlike most process documentation, it has a relatively long life. It must Evolve in step with the product that it describes. Product documentation includes User documentation, which tells users how to use the software product, System Documentation, which is principally intended for maintenance engineers. 17

18 What is the 2 main Categories of Users?

19 User Documentation Readers Users of a system are not all the same. The producer of documentation must structure it to cater for different user tasks and different levels of expertise and experience. It is particularly important to distinguish between end-users and system administrators: 1. End-users use the software to assist with some task. This may be flying an aircraft, managing insurance policies, writing a book, etc. They want to know how the software can help them. They are not interested in computer or administration details. 2. System administrators are responsible for managing the software used by end-users. This may involve acting as an operator if the system is a large mainframe system, as a network manager is the system involves a network of workstations or as a technical guru who fixes end-users software problems and who liaises between users and the software supplier. 19

20 Give Examples of detailed Technical Design Diagrams?

21 Technical Design Diagrams Database Diagrams (ER-diagrams) UML diagrams, eg., Use Case Digaram, Sequence Diagrams, Class Diagrams

22 Give an Overview of different types of Readers and what kind of Documents they read

23 Product Documentation Types & Readers To cater for these different classes of user and different levels of user expertise, several documents (or perhaps chapters in a single document) should be delivered with the software system. 23

24 What should the System Documentation include?

25 System Documentation Create System Documentation for your Systems. It can be one or more documents How the System Works (Technical), i.e use the Requirements & Design as base. Requirements & Design is about how it should be, while System Documentation is about how it became Includes Techical Design and Platform Overview, Database Diagram, UML diagrams, CAD drawings, Code Documentation, Flow Charts, with explainations, etc. How to deploy (how to install server-side logic), maintain, etc.

26 System Documentation System documentation includes all of the documents describing the system itself from the requirements specification to the final acceptance test plan. Documents describing the design, implementation and testing of a system are essential if the program is to be understood and maintained. Like user documentation, it is important that system documentation is structured, with overviews leading the reader into more formal and detailed descriptions of each aspect of the system. 26

27 System Documentation For large systems that are developed to a customer s specification, the system documentation should include: 1. The Requirements document. 2. A document describing the System Architecture. 3. For each program in the system, a description of the architecture of that program. 4. For each component in the system, a description of its functionality and interfaces. 5. Program Cource Code listings, which should be commented where the comments should explain complex sections of code and provide a rationale for the coding method used. If meaningful names are used and a good, structured programming style is used, much of the code should be self documenting without the need for additional comments. This information is now normally maintained electronically rather than on paper with selected information printed on demand from readers. 6. Validation documents describing how each program is validated and how the validation information relates to the requirements. These may be required for the quality assurance processes in the organization. 7. A System maintenance Guide, which describes known problems with the system, describes which parts of the system are hardware and software dependent and which describes how evolution of the system has been taken into account in its design 27

28 Give an Overview of different Types of Test Documentation

29 Test Documentation Software Test Plan (STP) Test Logs Planning Tests Perform Tests Document Test Results Software Design Document (SDD) Software Requirements Specifications (SRS) Software Test Documentation (STD) - Functional & Non-Functional Requirements - User & System Requirements These documents will be the foundation for all Testing 29

30 Software Test Plan (STP) A Document that answers the following: Testing should be based on Requirements & Design Documents What shall we test? How shall we test? Hardware/Software Requirements Where shall we test? Who shall test? How often shall we test (Test Schedule)? How shall tests be documented? It is not enough simply to run tests; the results of the tests must be systematically recorded. It must be possible to audit the testing process to check that it has been carried out correctly System tests: This section, which may be completely separate from the test plan, defines the test cases that should be applied to the system. These tests are derived from the system requirements specification. 30

31 Essentials of Software Engineering, Frank Tsui; Orlando Karam; Barbara Bernal, 3 ed., Jones & Bartlett Learning Appendix D in Essentials of Software Engineering Test Plan Example A. Goals and Exit Criteria (Quality, Robustness, Schedule, Performance Goals of the Product,...) B. Items to be Tested/Inspected (Executables such as modules and components, Nonexecutables such as Requirments and Design specifications,...) C. Test Process/Methodologies (Unit, Functional, Acceptance, Regression Tests, Black-box, White-box, Test metrics, Bug report process,... ) D. Resources (People, Tools, Test Environment,...) E. Schedule (Test-case development, Test execution, Problem reporting and fixing,...) F. Risks (...) G. Major Test Scenarios and Test Cases (...)

32 Test Plan Example 32 E. J. Braude and M. E.Bernstein, Software Engineering: Modern Approaches, 2 ed.: Wiley, (Ch. 25)

33 Test Plan Example Test Plan A test plan outlines the strategy that will be used to test an application, the resources that will be used, the test environment in which testing will be performed, the limitations of the testing and the schedule of testing activities. Typically the Quality Assurance Team Lead will be responsible for writing a Test Plan. A test plan will include the following. - Introduction to the Test Plan document - Assumptions when testing the application - List of test cases included in Testing the application - List of features to be tested - What sort of Approach to use when testing the software - List of Deliverables that need to be tested - The resources allocated for testing the application - Any Risks involved during the testing process - A Schedule of tasks and milestones as testing is started Reference: Software Testing Tutorial, tutorialspoint.com

34 Test Planning Test planning involves scheduling and estimating the system testing process, establishing process standards and describing the tests that should be carried out. As well as helping managers allocate resources and estimate testing schedules, test plans are intended for software engineers involved in designing and carrying out system tests. They help technical staff get an overall picture of the system tests and place their own work in this context. As well as setting out the testing schedule and procedures, the test plan defines the hardware and software resources that are required. Test plans are not a static documents but evolve during the development process. Test plans change because of delays at other stages in the development process. Test planning is particularly important in large software system development. For small and medium-sized systems, a less formal test plan may be used, but there is still a need for a formal document to support the planning of the testing process. 34

35 References Software Development - A Practical Approach Halvorsen, Hans-Petter, 2015 Essentials of Software Engineering Frank Tsui; Orlando Karam; Barbara Bernal, 3 ed., Jones & Bartlett Learning Software Engineering I. Sommerville, 10 ed.: Pearson, 2015 Software Engineering. Modern Approaches E. J. Braude and M. E.Bernstein, 2 ed.: Wiley,

36

37 Hans-Petter Halvorsen, M.Sc. University College of Southeast Norway Blog: