Which functional specifications are most important in an audio interface?

Specifications

• I have a program that supports interaction with other programs through DDE interface. As an engineer, but, not a programmer I would like to prepare specifications for programmers that work for me to incorporate certain commands from this program into other programs using the DDE interface. This protocol is mainly used to control program functions from 16-bit client application, which does not support the modern interface means (e.g. OLE Automation). As an engineer I know what functions I would like to see accessed by other programs. The question is how do I prepare a specification that includes a list of these desired functions and a brief description of what I expect the combined programs to achieve and how they should behave from a users point of view?

• Answer:

  Hi bert1-ga, Your query is one that has been asked time and time again by software developers. Luckily, standards have been defined that outline how to proceed with the development of non-trivial applications. First, let's consider the high-level stages of the SDLC (Software Development Life Cycle): "User Requirements definition Software Requirements definition Architectural Design Detailed Design and construction Delivery to the user Operations" http://ipt.web.cern.ch/IPT/Papers/Sopron94/CSCproceedings_10.html#HEADING9 At each stage of the SDLC, emphasis is placed on the creation and modification of supporting documentation. Some common types of documentation include: "User Manuals ­Reference Manuals­ Design Documents and Technical Specifications­ Software Life-Cycle Reports ­Customer reports­ Maintenance Reports­ Testing Reports­ Usage Reports ­etc." http://www.cee.hw.ac.uk/~ph/docs1.pdf Since your question deals with outlining specifications, the document(s) you need to compose fall under the "Design Documents and Technical Specifications" group. The most effective method of clearly laying out the various functions and interdependencies of a software application is by employing the use case methodology. Several Question/Answer pairs are laid out below to give you an idea of this concept: What is a Use Case? "A Use Case (also called a scenario) captures a contract between the stakeholders of a software system about its behavior. Use Cases describe the software system’s behavior under various conditions as it responds to requests by the users. Essentially, it provides an easy-to-understand representation of the functional requirements for a software system." Why are Use Cases an effective means of requirements gathering? "• They officially document the development process • They can separate the functional requirements from the business process • They serve as requirements documentation for software development • They are easy-to-read and easy-to-understand • They can be used to categorize and rank requirements • They can identify possible system/component reuse" Due to these benefits, Use Cases are now becoming customary as a method for gathering requirements. The answers to the above questions were adapted from an academic research paper, which I suggest you read closely for a full understanding of use cases. The appendix also includes a sample layout of a use case (though additional formatting could be added): http://www.bus.iastate.edu/nilakant/MIS538/Readings/Gather%20Req%20UC.pdf Each use case follows a consistent format - this is one that I have found useful yet concise: Actor (who can perform this function?) Precondition (what must occur before this function can be accessed?) Postcondition (what will happen once the function is complete?) Trigger (how does the system know when to perform this function?) Assumptions Main Scenario (includes what actor does and how system responds) 1. Step 1 2. Step 2 3. Step 3 4. Step 4 Alternate Scenario(s) (potential paths that could occur depending on input) Exceptions (possible ways the use case will not complete in a main/alternate scenerio fashion; for example, the actor decides half way through that they do not want to perform the function) Owner: (creator of use case) A single document is then created, typically called a requirements document, which includes all use cases along with some additional housekeeping information. Below is a format that I personally use to lay out this document (along with a brief description of each section): TABLE OF CONTENTS DOCUMENT CONTROL DOCUMENT LOCATION - where is "master" copy located? ACCEPTANCE - is this an external document that must be accepted by sponsor? REVIEW DISTRIBUTION - who has received the document for review? REVISION HISTORY - table of date, author, description of changes 1. EXECUTIVE SUMMARY - overview of the project's purpose and benefit 2. INTRODUCTION 2.1. DOCUMENT SCOPE - limits what application(s) is/are being considered 2.2. GLOSSARY - terminology used in document and meaning of each 3. GENERAL AND NON-FUNCTIONAL REQUIREMENTS 3.1. GENERAL REQUIREMENTS - high-level; could be groups of use cases 3.2. NON-FUNCTIONAL REQUIREMENTS - cannot be described as a function (ie. performance, ease of use, availability etc.) 4. SPECIFIC REQUIREMENTS 4.1. DESCRIPTION OF ACTORS - what is an actor; list and description of actors in this system 4.2. OVERVIEW OF USE CASES - listing and brief description of each use case 4.3. USE CASES 4.3.x. INPUT USE CASE x HERE 5. APPENDIX A – USE CASE PRIORITY AND EFFORT TABLE - listing/description of the main scenario and all alternative scenarios for each use case 6. APPENDIX B – SUMMARY OF FUTURE REQUIREMENTS - possible future additions to the application that has not yet been considered Although use cases are very useful in preparing the types of specifications you are looking for, it is useful (from my own personal experience) to also develop a test plan in parallel. A test plan is composed of a group of test cases, each of which correspond to one use case and lays out, in detail, how the successful development of a particular function should be verified. If necessary, test data should also be included with the test case for the tester(s) to use. This ensures that any variations in data entered are considered. The format for each individual test case is as follows: Name of the test (possible with a number for easy identification) Overview of the purpose of the test Equipment needed for the test Description of test setup Description of any additional hardware needed Description of dummy software front ends needed Description of data collection software needed Specific description of the inputs to be used in the test (Include specific "end point" data to be tested) Description of expected result for all data points tested (Include precision needed for numerical data) After you have completed your tests, you should add the following sections to each test case (leave these sections empty for now): "Test log and results Date and time test was performed Engineers involved in the test Any differences between the planned test and the actual test performed Table of measured data, if applicable Observations during test, if no numerical data taken Comments on test Overall result of test (Complete Pass/Partial Pass/Fail) and description of what did and didn't work. Signatures of all involved in the test." http://myhome.spu.edu/bolding/EE4211/design_notebook/test_plan.html Once all individual test cases have been designed, they can be collected and placed into a single document called a test plan. The outline of the test plan is as follows: 1. TABLE OF CONTENTS 2. DOCUMENT CONTROL 2.1. REVISION HISTORY - who/when/what for changes made 3. PROJECT OVERVIEW - description of the contents of the document 4. PURPOSE - what should be achieve with each test case 5. TEST MATRIX 5.1. FUNCTIONAL REQUIREMENTS MATRIX - ensures that each use case is tested at least once 5.2. STRUCTURAL REQUIREMENTS MATRIX - repeat info from general requirements in requirements document 5.3. TEST REQUIREMENTS COVERAGE MATRIX - alignment of test cases with use cases 6. TEST CASES 6.x. TEST CASE x - insert test case here (corresponding order with use cases) 7. TEST DATA 7.x. DATA FOR CASE x - data required as input for test case x You will have noticed that I have not talked about DDE or OLE in this discussion, and the reason for this is that requirement definition doesn't depend on which technology you employ to solve your problem. These documents are designed to provide a generic solution for ALL types of software projects and are useful in both technological and business environments. I hope you have found the above helpful in resolving your dilemma - if you have any problems understanding the information above please do feel free to post a clarification and I will respond promptly :) Cheers! answerguru-ga