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 to
delve 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 an
overview of the system and then move on to each component and its
function. This section as a whole needs to cover the explanation of the
way your application is structured and how the various pieces of it work
together.
3.1. System Overview
In this section, start with high-level architectural diagrams of the
system design, together with descriptions of the components used and
their relationships via a modeling language (UML is good for this). Also
include a description of the various modules that make up the system.
Going deeper, address all "global" aspects of the application. List and
describe the global configuration and runtime variables defined within
the system. Detailed information on where and how these variables are
stored can be included in an appendix.
Address your data storage next. Define the data structures used by the
system for system, configuration and user data and discuss the format of
their storage containers (whether they are databases, flat files or some
other format). Provide a brief explanation of the requirements that
resulted in the choice of a particular format, and address the resultant
constraints or benefits. The exact directory structure with file names
and instructions on how to back this data up before upgrading or
re-installing can be included in an appendix.
Next, explain the security and performance considerations. Describe the
user levels defined in the application, their access permissions and the
techniques used by you to ensure data protection. Also talk about the
performance enhancing techniques incorporated, their effects and their
constraints - 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 should
explain the purpose of each component, its functions, its data input and
output formats, its input and output interfaces, its internal business
logic, and its interaction with other components. You can include
pseudo-code wherever needed to ensure that the details are clearly
communicated.
On the whole, this section will be similar in structure to the system
overview except that you will be describing a component instead of the
system.
Your heads of information could be:
* Scope of functions
Talk briefly about what the component does and the requirement it
fulfills.
* Block diagram
This diagram should highlight the structure of the component, displaying
the sub-components, if any, and the local APIs. You may choose not to
have this block diagram if the component is a single unit without any
further sub-components.
* Control flow diagram
This diagram should depict the flow within the component for execution
of its function(s). Highlight the input and output paths, the events
that trigger the component APIs, and the points at which this component
interacts with other components.
Explain the flow depicted in the diagram in detail - describe the
input/output instances and describe the data formats, the events that
trigger the local/private APIs and the events that trigger interaction
with other components (you can describe the local APIs in detail in the
next section). Similarly, while talking about the interaction with other
components, introduce the system interfaces (public APIs) called, and
reference 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, boundary
conditions and return values.
* Configuration and run time variables
List the variables relevant to the component, with a brief description
of each, allowed values or value range and data type.
* Data Structure
Since you have already defined the system-wide data structures, talk
about other data structures used by the component, if any.
* Sub-components
If sub-components exist, list them here and, for each, briefly describe
all the above heads of information.
* Exception handling and error types
Discuss the errors you have anticipated and how your exception handler
will 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 - and
they are depicted differently to help the user identify them. For
example, error types may be color coded within the application for easy
identification - talk about these conventions and what each one
signifies too.
* Diagnostics
Finally, talk about the logs and reports generated by this component.
Discuss the method of accessing these logs, filters available to sift
through them, and the formats in which they are generated. You could
provide samples and discuss detailed log analysis or troubleshooting in
an appendix.
3.3. System APIs
Talk about the interfaces between components here (public APIs). Since
you will have introduced most of these APIs while describing the flow of
the components, this section could simply be information on their access
methods, boundary conditions, arguments needed and return values.
3.4. System Interfaces
This section will address any interfacing that the system needs to do
with other existing systems in the customer's office. For example, if
your application is to automate the generation of employee salary/bonus
statements, it would possibly interface with the accounting system to
extract the salary info for the salesmen, and with the sales system to
calculate sales per person and corresponding commission/bonus payable.
In such cases, describe the instances of data extraction/insertion, data
formats, the necessary configurations and back-up considerations for
each interface.
