Product documentation architectural tweaks.pptx


Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Product documentation architectural tweaks.pptx

  1. 1. Product DocumentationArchitectural TweaksGirish MahadevanKnowledge services – Technical Writer30/09/2010
  2. 2. PurposeTo tweak the existing Savvion documents, and propose and discussimprovements. 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. 3. Existing DocumentsThe existing documents are designed with an intent to provide completesoftware related information to the users. The following media gets bundledand shipped with the software kit:1. Developer guides2. User guides3. Manager guides4. Administrator guides5. TutorialsThese documents by all means are mutually exhaustive of Progress Savvionproduct information, but they can be further improved with DITAimplementation, and can be standardized to give a better look and feel.
  4. 4. Document StructureScope 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. 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. 6. Document Structure - RedundancyExisting 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. 7. Document Structure – Image UsageProposed 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 theExisting 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. 8. Proposed TOCExisting Proposed Rearranging TOC for better archiving and readability. Mainly, ensuring topic flow to match product UI.
  9. 9. Improving ReadabilityDocument structure improvement will definitely improve readability, butafter structural changes, we can work on the following to improvereadability. 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. 10. Topic NavigationSavvion documents are really complex to navigate for new users. Aworkflow 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, whereto 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. 11. Content MergingThere is a lot of content in different documents which can be merged andpresented as one document. DITA facilitates the same, for example, instead ofhaving multiple developer‟s guide, we can have one developer‟s guide for alldevelopers.Existing1. Application Developer‟s guide2. BizLogic Developer‟s guide3. BizPulse Developer‟s guideSuggestion1. Developer‟s guide • Application Developer‟s guide • BizLogic Developer‟s guide • BizPulse Developer‟s guide
  12. 12. Document ShippingThere are 23 Flash Demos along with instructor‟s and student‟s guide, thesecan be shipped with the software product. These videos demonstratefunctions and operations of BPM studio, they are standalone and do notappear in the documents. We can integrate them within the documents.
  13. 13. Thank You