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 todiscuss what the user actually sees - the user interface - together withadministration 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 theinterface has been developed, the browsers supported (in case of a Webapplication) and the display settings required.
An explanation of how the interface has been coded, and instructions forcustomizing/duplicating those pages should also be included here. Forexample, if you have used templates to develop your interface andseparate the business logic from the interface, you would need toexplain the sub-division of the interface as various templates, localand global variables, the API used to connect the templates with thecontent.
While you could use this section to describe/give examples of each ofthe above aspects, the appendix must contain a detailed list of thelocal and global variables defined, the template files and theirlocations, and the program files and their location. Providewell-commented code samples to clarify things as needed.
5. Administration/Control
In this section, list the various methods of accessing administrativetools. For each method, list the options (Web interface or console). Foreach of these options, you could further explain the format/protocolexpected, available functions and default and recommended settings.
6. Appendices
For each section of the TOC, abstract out chunks of information thatwould distract from the main purpose of discussion, but which arerelevant nevertheless. These items can be discussed in detail in theappendices. The following are some recommendations:
* Manual backup/restore proceduresIn case your application does not provide for backup and restoration ofuser data, you would need to provide instructions on the manual processto accomplish this. Including a list of the data storage containersused, their formats and sizes, and recommended usage capacity would behelpful as well.
* Data structures
For all the data structures used in the system, provide detailedinformation on the data storage containers, their formats and alloweddata types, and sizes or maximum capacities.
* Interface elements
List all the variables and files related to the user interface, togetherwith diagrams or screen flow charts explaining how the various screensare 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 forvariable and function definitions. Also describe the format, style andlength of function names, variable names, file names, and database andtable names.
* Installation packages
Instructions on how to (re)build or compile the software from sourcecode.
* Logs and reports
Samples of logs and reports along with a discussion on how they may beanalyzed. If your applications includes tools or filters to assist inthis process, a discussion of how these tools may be used, together withsample scenarios.
* References
Mention the other documents delivered with the application, with a briefdiscussion of what each one covers and their version numbers.
* Development history
A development history of the application is also useful, especially forapplications that are constantly under development. The best way to goabout this is to show a timeline of the various versions, together witha list of the important features added at each stage. For example, ifyour application uses the "xx.yy" system of version numbering (with "xx"being incremented for baseline changes and "yy" being incremented forintermediate releases), you can provide a brief snapshot of theapplication at each baseline and intermediate release.
Next: Improving Yourself >>
More Practices Articles
More By Deepa L, (c) Melonfire
