Home arrow Practices arrow Page 4 - Writing A Software Technical Reference Manual (part 2)

Remote Control - Practices

With the groundwork out of the way, this concluding partexamines the standard components of a technical reference manual,explaining what goes into each section and why. It also discusses theprocess by which such a manual should be reviewed and vetted prior todelivery to a customer.

  1. Writing A Software Technical Reference Manual (part 2)
  2. Starting Off Easy
  3. System Shock
  4. Remote Control
  5. Improving Yourself
  6. Sealed With A Kiss
By: Deepa L, (c) Melonfire
Rating: starstarstarstarstar / 3
February 13, 2003

print this article


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.

>>> More Practices Articles          >>> More By Deepa L, (c) Melonfire

blog comments powered by Disqus
escort Bursa Bursa escort Antalya eskort


- Calculating Development Project Costs
- More Techniques for Finding Things
- Finding Things
- Finishing the System`s Outlines
- The System in So Many Words
- Basic Data Types and Calculations
- What`s the Address? Pointers
- Design with ArgoUML
- Pragmatic Guidelines: Diagrams That Work
- Five-Step UML: OOAD for Short Attention Span...
- Five-Step UML: OOAD for Short Attention Span...
- Introducing UML: Object-Oriented Analysis an...
- Class and Object Diagrams
- Class Relationships
- Classes

Developer Shed Affiliates


Dev Shed Tutorial Topics: