The document discusses proposed improvements to existing Savvion product documentation. It identifies issues with document structure including redundant information, unclear terminology in tables of contents, and lack of navigation aids. It recommends consolidating related topics, adding hyperlinks, reorganizing tables of contents, and integrating tutorial videos directly into the documentation for easier navigation and a better user experience. A revised start page and merging similar guides are also proposed to enhance readability and usability of the documentation.

1. Product Documentation
Architectural Tweaks
Girish Mahadevan
Knowledge services – Technical Writer
30/09/2010

2. Purpose
To tweak the existing Savvion documents, and propose and discuss
improvements.
 Existing documents
 Document Structure
• Redundancy
• User Specific Terms
• Revamping the TOC
 Material readability
• Start Page
 Topic Navigation
• Related Topic section
• Hyper linking
 Content Merging
 Document Shipping

3. Existing Documents
The existing documents are designed with an intent to provide complete
software related information to the users. The following media gets bundled
and shipped with the software kit:
1. Developer guides
2. User guides
3. Manager guides
4. Administrator guides
5. Tutorials
These documents by all means are mutually exhaustive of Progress Savvion
product information, but they can be further improved with DITA
implementation, and can be standardized to give a better look and feel.

4. Document Structure
Scope for improvement in Document Structure
 Improvement in TOC tree
It becomes a little troublesome for users to navigate to the correct chapter
if they are not structured properly.
 General User specific terms in TOC
TOC should clearly map a child topic inside a parent topic. There should be
defined books or buckets of “Development”, “Deployment”, and
“Tutorials”. These terms will allow a document to be used as required,
either as reference material or training material.
 Redundant information
Information repetition should be avoided. Information which provides basic
operations such as „selecting a date‟ should be removed as they have
become very generic and need not be explicitly stated in product
documents.

5. Document Structure
 Implementing Agile process
We need to provide a download link in the beginning of each document
which takes users to the latest release documents.

6. Document Structure - Redundancy
Existing
Proposed
The content in ‘User Types’
and ‘BusinessManager User
Types’ are the same. To
reduce redundancy, we
should retain this topic in just
Preface because it’s not a
part of SBM Overview.

7. Document Structure – Image Usage
Proposed Description of the task: In the Home
module, a downward pointing triangle
beside the column header indicates
that the listed items
can be sorted on that column header.
Click the column to display the
Existing sorting options.
For beginners, the proposed snapshot
provides a better guidance than the
snapshot below. It becomes easier
for users to reproduce the steps in
the documentation.

8. Proposed TOC
Existing Proposed
Rearranging TOC for
better archiving and
readability. Mainly,
ensuring topic flow to
match product UI.

9. Improving Readability
Document structure improvement will definitely improve readability, but
after structural changes, we can work on the following to improve
readability.
 Start page
The Savvion documentation has an index.html page which gives an
overall picture of all the product documents. This is not as efficient
as a start.pdf in Progress OpenEdge documentation. We need to
provide a start.pdf for Savvion to ensure easier navigation and
readability.

10. Topic Navigation
Savvion documents are really complex to navigate for new users. A
workflow for a user should be facilitated i.e. when a person hits a topic,
he needs to know what to do with the topic, where to implement, where
to go next, and what is related.
 Related topic section
Which informs the users about what is following and what else might
interest the user for further reading.
 Hyper linking
There are a lot of concepts which a user requires to fall back to for
clearance. We need to link all these keywords/phrases to their
respective definition/tutorial/How-to.

11. Content Merging
There is a lot of content in different documents which can be merged and
presented as one document. DITA facilitates the same, for example, instead of
having multiple developer‟s guide, we can have one developer‟s guide for all
developers.
Existing
1. Application Developer‟s guide
2. BizLogic Developer‟s guide
3. BizPulse Developer‟s guide
Suggestion
1. Developer‟s guide
• Application Developer‟s guide
• BizLogic Developer‟s guide
• BizPulse Developer‟s guide

12. Document Shipping
There are 23 Flash Demos along with instructor‟s and student‟s guide, these
can be shipped with the software product. These videos demonstrate
functions and operations of BPM studio, they are standalone and do not
appear in the documents. We can integrate them within the documents.

13. Thank You