Application Software Documentation Design

Documentation Design

Documentation Design - FOREWORD

This may not always reflect the “state-of-the-art” in methodology, but it does provide an illustration of the issues and approach for reference documentation design.

Finalise Reference Documentation Design

Objectives:

• Identify the additional reference materials needed for customer management, user and MIS support personnel to effectively operate the new system, take full advantage of its capabilities and minimise the effects from turnover

Hints:

• Reference documentation provided by the supplier is usually written in generic terms and is limited to the standard system functions and operations.  This provides an opportunity to develop additional reference material covering customer-specific manual procedures, workflow and operations.  However, it is important to balance the value added from custom-developed reference documentation with the ongoing cost of maintaining it.  Supplementary reference documentation may include:
• System Reference Guide – customer-specific instructions on using the system functions
• User Reference Guide – customer-specific instructions on performing the related manual procedures
• Operations Reference Guide – technical instructions on executing system processes
• Management Reference Guide – functional system overview with emphasis on on-line inquiry and reporting.
• In developing procedures for manual tasks, special attention should be given to finding ways to eliminate unnecessary tasks and streamlining the entire flow of information.  This requires looking beyond what is being done and evaluating why it is being done.
• If available, the Implementation Strategy Report developed during the evaluation and selection process can provide a starting point for determining the detailed reference and documentation requirements for the new system.

Steps:

• Evaluate the impact of the new system on existing manual procedures and company policies
• Transaction preparation, review and approval workflow
• Transaction entry and reconciliation
• Security, audit trails and controls
• Form and report filing and retention
• System support, maintenance and implementation of enhancements
• Evaluate the system impact on the technical support and operations procedures
• Data collection and entry cutoffs
• System processing, report generation and distribution schedules
• System operations and technical support coverage
• Backup frequencies and retention periods
• System maintenance and enhancement
• Manual change control
• Implementation tasks
• Identify any significant organisation improvements to maximise workflow efficiency and effectiveness
• Organisation structure
• Reporting responsibilities
• Manpower requirements
• Position responsibilities
• Individual skills or expertise
• Identify any outside parties that would be affected by the new system
• Customers
• Banks
• Vendors
• Service bureau
• Auditors
• Review existing customer manuals and supplier-provided manuals, identify any supplementary reference documentation needed and prepare tables of contents
• System guide
• User guide
• Operations guide
• Management guide
• Determine content and distribution of reference documentation to be developed
• Level of detail
• Format
• Number of copies
• Printing and binding
• Distribution list
• Ongoing maintenance and control
• Evaluate reference documentation alternatives and select approach
• Complexity
• Cost
• Resources
• Timeframe
• Organisational Impact
• Organise analysis and prepare Implementation Papers for reference documentation:
• Background
• Requirements
• Alternative options
• Recommended approach and justification
• Details of recommended approach
• Review Implementation Papers with customer sponsor and obtain approval

Tools:

• Implementation Strategy Report (from evaluation and selection)
• Example: Management Reference Guide TOC
• Example: Operations Reference Guide TOC
• Example: System Reference Guide TOC
• Example: User Reference Guide TOC

Deliverables:

• Reference Documentation Implementation Paper