Writing A Software Technical Reference Manual (part 2) - Remote Control (
Page 4 of 6 )
Once the business logic of the application is done with, it's time to
discuss what the user actually sees - the user interface - together with
administration issues and processes.
4. User Interface
This section will touch upon the user interface of your application.
Information to be highlighted here would be the platform on which the
interface has been developed, the browsers supported (in case of a Web
application) and the display settings required.
An explanation of how the interface has been coded, and instructions for
customizing/duplicating those pages should also be included here. For
example, if you have used templates to develop your interface and
separate the business logic from the interface, you would need to
explain the sub-division of the interface as various templates, local
and global variables, the API used to connect the templates with the
content.
While you could use this section to describe/give examples of each of
the above aspects, the appendix must contain a detailed list of the
local and global variables defined, the template files and their
locations, and the program files and their location. Provide
well-commented code samples to clarify things as needed.
5. Administration/Control
In this section, list the various methods of accessing administrative
tools. For each method, list the options (Web interface or console). For
each of these options, you could further explain the format/protocol
expected, available functions and default and recommended settings.
6. Appendices
For each section of the TOC, abstract out chunks of information that
would distract from the main purpose of discussion, but which are
relevant nevertheless. These items can be discussed in detail in the
appendices. The following are some recommendations:
* Manual backup/restore procedures
In case your application does not provide for backup and restoration of
user data, you would need to provide instructions on the manual process
to accomplish this. Including a list of the data storage containers
used, their formats and sizes, and recommended usage capacity would be
helpful as well.
* Data structures
For all the data structures used in the system, provide detailed
information on the data storage containers, their formats and allowed
data types, and sizes or maximum capacities.
* Interface elements
List all the variables and files related to the user interface, together
with diagrams or screen flow charts explaining how the various screens
are built and connected to each other.
* Coding standards
Discuss the conventions followed while coding - block indentation,
script header and footer blocks, script revision logs, and comments for
variable and function definitions. Also describe the format, style and
length of function names, variable names, file names, and database and
table names.
* Installation packages
Instructions on how to (re)build or compile the software from source
code.
* Logs and reports
Samples of logs and reports along with a discussion on how they may be
analyzed. If your applications includes tools or filters to assist in
this process, a discussion of how these tools may be used, together with
sample scenarios.
* References
Mention the other documents delivered with the application, with a brief
discussion of what each one covers and their version numbers.
* Development history
A development history of the application is also useful, especially for
applications that are constantly under development. The best way to go
about this is to show a timeline of the various versions, together with
a list of the important features added at each stage. For example, if
your application uses the "xx.yy" system of version numbering (with "xx"
being incremented for baseline changes and "yy" being incremented for
intermediate releases), you can provide a brief snapshot of the
application at each baseline and intermediate release.
