Feature Specification

Feature Name: Integrated Help System

Overview

This specification will attempt to detail the requirements and also solutions for delivering a more fully-integrated help system and documentation infrastructure.

I: Problem: Users need help when they need it and where they need it (i.e., context-sensitive help)

1. From within the guiclient -- options include
   
   1. Window/frame/drawer part of app
   2. Web browser next to app
   3. Qt Assistant next to app
   4. Others?
2. How to show reference guide about the widget surrounded by reference guide about the window?

3. How to show how to use the widget as well as what role the widget plays in this window?

4. How to provide access to additional info: web pages, videos, forums, issue tracker?
5. Non-core documentation must be displayed using the same mechanism
6. "Blockout the noise" by "targeting the results"
   
   1. Filter appropriately
   2. Hide unnecessary distractions (e.g., the fact that we might be browsing the web; the fact that this is a mantis issue page; the difference between core and package functionality; the difference between xTuple and third-party docs

II: External parties contribute code and docs

1. External docs need to conform to our standards
2. We need to define the standards
3. Should third-party docs be required to conform to our standards to be listed on the xChange? If so, conformity must be verified before listing goes live

III: Problem: Distribution of docs

1. Installation process for core docs
2. Installation process for package docs
3. Different classes of docs: Reference guide ≠ topics ≠ community contributed ≠ user guide(s)/product guide(s) ≠ bug history, etc.
4. Online ≠ hard copy
5. Local to end user ≠ central at use site ≠ hosted by xTuple

IV: Searchable help -- user-initiated

1. Over the web
2. Locally
3. Package-specific if integrated (see I.5, II.3, and III.2)
4. Should include relevant solutions available on the xChange

V: Multiple navigation styles

1. TOC
2. Search
3. Index

VI: Content should be reusable and repurposeable

1. One piece might be used in the Reference Guide and a product guide (e.g., Retail Guide) and also the help system
2. Some might include screenshots and some might not

VII: Help system needs to support more than just xTuple ERP main client

1. xTuple ERP
2. Updater
3. CSVimp
4. OpenRPT
5. Batch Manager
6. Installer -- Bitrock

VIII: Multiple versions of product

1. 3.2.1 client needs to see different content than 3.1.0 client

2. Search should not exclude other versions entirely because a search might reveal that a bug existed in 3.1.0 but was fixed in 3.2.0

IX: Reduce the burden imposed by maintaining screenshots

1. Could a unique docs-only Squish script be written for the purpose of generating screenshots?
   
   1. If so, could be path to OS-specific screenshots (i.e., run screenshot script in Windows, Mac, Linux clients)

X: Translation of documentation

1. The system should anticipate and support international users who will need to translate the documentation into several languages
2. This support should apply to xTuple core docs and also package or third-party docs

3. UI translation is currently handled by the Translation Portal; however, we need a method for supporting translation of error messages (see XI).

XI: Error message translation

1. Need methodology for facilitating the translation of error messages

Functional Requirements

List what the application must do. This section is for the sole purpose of describing the problem to be solved by this feature. There are other sections below for proposed solutions to this problem and meeting all of the requirements, what the application will look like, what the window changes will be, etc.

New Terms and Definitions

This is the place to define new words and phrases to be used in the application and the documentation. If this feature introduces a new concept or changes the semantics of an existing concept in the application then define it here. Define it even if you think the definition should be obvious, since your definition might not match the definition used by the reader, like so:

• context-sensitive help

  • Providing users with the help they need when they need it and where they need it

• revised concept

  • new definition, followed by how the new semantics differ from the old

Related Existing Functionality

What does the application do now that is similar to the requested functionality?

Similar and Related Requests

What other requests have we gotten that might tie in nicely with this feature?

What open issues might be addressed by this feature?

Try to create hyperlinks to web-accessible data, such as this link to Mantis issue 2949.

Conflicting Features

What features currently exist and what feature requests have we received that might conflict with the feature described here?

User-Level Functionality

Describe how the new functionality will appear to and behave for the application user. To write this properly you will need to jump back and forth between this section and the Internal Design section.

Describe the menu changes and overall application structure changes here then get detailed in the subsections.

Window Changes

What windows do we expect to change?

What windows do we expect to eliminate?

What windows do we expect to add?

Insert screen shots of window mock-ups like this:

[Insert image here.]

Describe what each window does, what its fields mean, what the buttons do, what right-click menu items are available in the list views, etc.

Report Changes

What reports do we expect to create, eliminate, or change?

Batch Manager Changes

What functionality do we expect to add to, remove from, or change in the Batch Manager?

Usability Considerations

How do we think this will affect user access to existing functionality?

What problems do we anticipate users might have with this functionality and how can we minimize the impact of these problems?

What errors or abnormal situations do we expect users might encounter during normal processing and how can we make it easy for the user to fix these problems using the application?

Problems and Alternatives

What might go wrong with the solution described in this document?

Why might this not be the best solution?

What are the limitations of this approach? What's missing that might be desirable?

Describe briefly other ways to solve the basic problem and the advantages and disadvantages of each alternative.

Justify the chosen solution or argue why one of the alternatives would be better. Be as broad as possible here, since an important purpose of this section is to provide alternatives in case the initial attempt at implementation encounters a significant implementation block.

Internal Design

Now that we have defined what we have to do and how we think it should look to the user, we can describe the internal structure of the application. If possible, outline the architecture of the feature implementation here. Then in the sections below describe the changes and additions to the application to create this architecture.

Basic Algorithms

Are there particular algorithms required to implement this feature? If so, describe them here.

If you are going to outline a particular algorithm in pseudo-code
    put it in a programlisting
    try to limit lines to approximately 80 characters
    try to limit programming constructs while still being clear about intent
end if // a programming construct that may be unavoidable to maintain clarity

Custom Widget Changes

Do we expect to modify existing custom widgets to support the windows described above?

What new custom widgets will we need? Will they be derived from existing widgets? What behavior do we expect from them?

Schema Changes

What changes do we anticipate making to the database schema? New tables? Views? Indexes?

The new whatever-you-call-it table

What privileges do we need?

Stored Procedure Changes

What stored procedures do we expect to create, eliminate, or change?

Performance Considerations

How will this feature impact the performance of the application overall?

 

Error Handling

What internal errors do we anticipate might occur?

How can we best hide them from the user, prevent them, or fix them automatically?

 

QA Considerations

Does this feature require any special tools or data to test? Is it testable (some features may be hard to reach from the user level)?

What are some anticipated areas of concern that require special attention?

 

Documentation Considerations

Is there a significant documentation impact?

Does the feature require a standalone essay or only field-level descriptions?

 

Release Considerations

What release would we like to target?

What is the potential impact on a release if we don't finish in time?

What happens if we only get some of the functionality done?

Are there any pieces that would be useful on their own?

Are there any dependencies on other features or applications (such as Qt 4 or a particular release of OpenRPT)?

What is the anticipated impact on users, particularly those who have customized the sources, reports, and database schema?