Writing A Software Technical Reference Manual (part 2) - System Shock
(Page 3 of 6 )
Once you've got the introductory material out of the way, it's time todelve into the nitty-gritty of system and component design and function.
3. System
This is the meat of the document. The idea here is to first present anoverview of the system and then move on to each component and itsfunction. This section as a whole needs to cover the explanation of theway your application is structured and how the various pieces of it worktogether.
3.1. System Overview
In this section, start with high-level architectural diagrams of thesystem design, together with descriptions of the components used andtheir relationships via a modeling language (UML is good for this). Alsoinclude a description of the various modules that make up the system.
Going deeper, address all "global" aspects of the application. List anddescribe the global configuration and runtime variables defined withinthe system. Detailed information on where and how these variables arestored can be included in an appendix.
Address your data storage next. Define the data structures used by thesystem for system, configuration and user data and discuss the format oftheir storage containers (whether they are databases, flat files or someother format). Provide a brief explanation of the requirements thatresulted in the choice of a particular format, and address the resultantconstraints or benefits. The exact directory structure with file namesand instructions on how to back this data up before upgrading orre-installing can be included in an appendix.
Next, explain the security and performance considerations. Describe theuser levels defined in the application, their access permissions and thetechniques used by you to ensure data protection. Also talk about theperformance enhancing techniques incorporated, their effects and theirconstraints - for example, caching and platform-specific tuning options.You may choose to relegate the details like the cache size, location,backup considerations and customizing options to an appendix.
3.2. Component Overview
Drilling deeper into the application components, this section shouldexplain the purpose of each component, its functions, its data input andoutput formats, its input and output interfaces, its internal businesslogic, and its interaction with other components. You can includepseudo-code wherever needed to ensure that the details are clearlycommunicated.
On the whole, this section will be similar in structure to the systemoverview except that you will be describing a component instead of thesystem.
Your heads of information could be:
* Scope of functions
Talk briefly about what the component does and the requirement itfulfills.
* Block diagram
This diagram should highlight the structure of the component, displayingthe sub-components, if any, and the local APIs. You may choose not tohave this block diagram if the component is a single unit without anyfurther sub-components.
* Control flow diagram
This diagram should depict the flow within the component for executionof its function(s). Highlight the input and output paths, the eventsthat trigger the component APIs, and the points at which this componentinteracts with other components.
Explain the flow depicted in the diagram in detail - describe theinput/output instances and describe the data formats, the events thattrigger the local/private APIs and the events that trigger interactionwith other components (you can describe the local APIs in detail in thenext section). Similarly, while talking about the interaction with othercomponents, introduce the system interfaces (public APIs) called, andreference detailed notes in other sections of the document.
* Component APIs
Having introduced the component APIs, describe them here. For each API,include information on its access method (socket, local function call,remote function call and so on), the arguments to be provided, boundaryconditions and return values.
* Configuration and run time variables
List the variables relevant to the component, with a brief descriptionof each, allowed values or value range and data type.
* Data Structure
Since you have already defined the system-wide data structures, talkabout other data structures used by the component, if any.
* Sub-components
If sub-components exist, list them here and, for each, briefly describeall the above heads of information.
* Exception handling and error types
Discuss the errors you have anticipated and how your exception handlerwill deal with them. Also define the error types you have identified.
Commonly, the error types are based on severity of the problem -notification, warning, or fatal error are the three most common - andthey are depicted differently to help the user identify them. Forexample, error types may be color coded within the application for easyidentification - talk about these conventions and what each onesignifies too.
* Diagnostics
Finally, talk about the logs and reports generated by this component.Discuss the method of accessing these logs, filters available to siftthrough them, and the formats in which they are generated. You couldprovide samples and discuss detailed log analysis or troubleshooting inan appendix.
3.3. System APIs
Talk about the interfaces between components here (public APIs). Sinceyou will have introduced most of these APIs while describing the flow ofthe components, this section could simply be information on their accessmethods, boundary conditions, arguments needed and return values.
3.4. System Interfaces
This section will address any interfacing that the system needs to dowith other existing systems in the customer's office. For example, ifyour application is to automate the generation of employee salary/bonusstatements, it would possibly interface with the accounting system toextract the salary info for the salesmen, and with the sales system tocalculate sales per person and corresponding commission/bonus payable.In such cases, describe the instances of data extraction/insertion, dataformats, the necessary configurations and back-up considerations foreach interface.
Next: Remote Control >>
More Practices Articles
More By Deepa L, (c) Melonfire
