Application Help Content Management and Delivery: Difference between revisions
(Created page with '==Overall== OpenPetra currently does not have application help (usually launched with the 'F1' key). The goal of this project is to '''set up the ''technical platforms for editi…') |
No edit summary |
||
| Line 3: | Line 3: | ||
The goal of this project is to '''set up the ''technical platforms for editing, creating and publishing'' of the application help with the aim of having the application help output in the so-called 'WebHelp' format. | The goal of this project is to '''set up the ''technical platforms for editing, creating and publishing'' of the application help with the aim of having the application help output in the so-called 'WebHelp' format. | ||
''Writing the content is not part of this project'' (with the exception of the creation of | ''Writing the content is not part of this project'' (with the exception of the creation of limited content to prove that the technical platforms work as desired). | ||
The technical | The technical platform should be Confluence or Calenco, as mentioned in the section '[[Common Goals for the Two Documentation-related Projects#Tools_for_Evaluation|Tools for Evaluation]]', for the major parts of what we want to achieve with this project. | ||
| Line 16: | Line 16: | ||
Also, the help system must be accessible "online" and "offline". | Also, the help system must be accessible "online" and "offline". | ||
* With 'online' we mean that the Help system can be accessed via a website, like the 'Calenco' documentation which is found [http://doc.neodoc.biz/user/content/pr01.html here]). The advantage of this is that the content can be kept highly up-to-date. | * With 'online' we mean that the Help system can be accessed via a website, like the 'Calenco' documentation which is found [http://doc.neodoc.biz/user/content/pr01.html here]). The advantage of this is that the content can be kept highly up-to-date. | ||
* With | * With 'offline' we mean that the Help system needs to work ''totally without any Internet connection'', which is not easy if one wants a full-text search ability and one does not want to install a local webserver on the user's machine, which would be overkill just for achieving that. WebHelp has that offline capability even for the full-text search. | ||
''The application help output we have chosen with DocBook's 'WebHelp' meets all those key requirements.'' | ''The application help output we have chosen with DocBook's 'WebHelp' meets all those key requirements.'' | ||
=== URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified === | === URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified === | ||
''' | The ''part of the URL'' that opens the correct help article in the web browser when the user presses the 'F1' function key ''must not change'', e.g. it must stay the same when new help topics are added or some help topics are deleted. The part of the URL could be an ID or a string identifier, for instance. The reason for the 'static-ness' is that the ID's (or whatever identifies the article uniquely) need to be 'wired up' to the F1 handling code inside the OpenPetra application so that the correct Help page is opened on user request, no matter how much the content in the help system has been changed since that 'wiring up' took place. This is needed esp. for the 'online' Help access, but could be needed for 'offline' Help access as well if one wants to publish offline Help content updates without the need for updating the 'wiring up' in the application's binaries. | ||
Note: By default the URL Parts that are generated with WebHelp ''are NOT static'' and change when new help pages are added between help pages! | |||
Solution for Confluence: Using the 'page name' of Confluence. This works as long page names don't change! There is also a 'pageId', which is the unique id in the Confluence database which could also be used, but that approach doesn't work if one migrates or copies Confluence spaces, etc. (which will be done for Application Versioning [V1.0, V1.5, ...] reasons!). | |||
==Optional Features== | ==Optional Features== | ||
| Line 32: | Line 35: | ||
==Expected Outcome== | ==Expected Outcome== | ||
===General=== | ===General=== | ||
Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones [[Common Goals for the Two Documentation-related Projects#Expected_Outcome|here]], should be made with both | Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones [[Common Goals for the Two Documentation-related Projects#Expected_Outcome|here]], should be made with both Confluence and Calenco. | ||
Once this is done with both products, a write-up should be done of the 'pros' and 'cons' of each | Once this is done with both products, a write-up should be done of the 'pros' and 'cons' of each product. | ||
'''Based on the write-up we will make a judgement. We are then planning to use our favoured product for the purposes of authoring application help for OpenPetra.''' | '''Based on the write-up we will make a judgement. We are then planning to use our favoured product for the purposes of authoring application help for OpenPetra.''' | ||
===WebHelp Output=== | ===WebHelp Output=== | ||
The default WebHelp output is pretty good. What we would want to customise is exchanging of the DocBook logo with the OpenPetra logo and perhaps have some CSS tweaking done for the layout. | |||
===Optional/Bonus: Integration into OpenPetra ('F1'-Key Hookup)=== | ===Optional/Bonus: Integration into OpenPetra ('F1'-Key Hookup)=== | ||
'''TODO''' | '''TODO''' | ||
Revision as of 19:04, 8 January 2012
Overall
OpenPetra currently does not have application help (usually launched with the 'F1' key).
The goal of this project is to set up the technical platforms for editing, creating and publishing of the application help with the aim of having the application help output in the so-called 'WebHelp' format. Writing the content is not part of this project (with the exception of the creation of limited content to prove that the technical platforms work as desired).
The technical platform should be Confluence or Calenco, as mentioned in the section 'Tools for Evaluation', for the major parts of what we want to achieve with this project.
Requirements
The requirements listed here are in addition to what is listed in the section 'Requirements'!
Key Requirements: Met Automatically by DocBook's 'WebHelp'
The key requirements for the Help system we are aiming to have that is that it needs to be able to run in a web browser, run cross-platform (Windows, Linux and Apple OS X), must have a full-text search, and translations must be possible.
Also, the help system must be accessible "online" and "offline".
- With 'online' we mean that the Help system can be accessed via a website, like the 'Calenco' documentation which is found here). The advantage of this is that the content can be kept highly up-to-date.
- With 'offline' we mean that the Help system needs to work totally without any Internet connection, which is not easy if one wants a full-text search ability and one does not want to install a local webserver on the user's machine, which would be overkill just for achieving that. WebHelp has that offline capability even for the full-text search.
The application help output we have chosen with DocBook's 'WebHelp' meets all those key requirements.
URL Part That Specifies a Help Topic Must Remain the Same if Content is Modified
The part of the URL that opens the correct help article in the web browser when the user presses the 'F1' function key must not change, e.g. it must stay the same when new help topics are added or some help topics are deleted. The part of the URL could be an ID or a string identifier, for instance. The reason for the 'static-ness' is that the ID's (or whatever identifies the article uniquely) need to be 'wired up' to the F1 handling code inside the OpenPetra application so that the correct Help page is opened on user request, no matter how much the content in the help system has been changed since that 'wiring up' took place. This is needed esp. for the 'online' Help access, but could be needed for 'offline' Help access as well if one wants to publish offline Help content updates without the need for updating the 'wiring up' in the application's binaries.
Note: By default the URL Parts that are generated with WebHelp are NOT static and change when new help pages are added between help pages!
Solution for Confluence: Using the 'page name' of Confluence. This works as long page names don't change! There is also a 'pageId', which is the unique id in the Confluence database which could also be used, but that approach doesn't work if one migrates or copies Confluence spaces, etc. (which will be done for Application Versioning [V1.0, V1.5, ...] reasons!).
Optional Features
The requirements listed here are in addition to what is listed in the section 'Optional Features'!
Users Can Leave Comments on Topics
Integrate a User Comment Form as found here ('Post a Comment on xyz' section of the web page).
Expected Outcome
General
Attempts to realise the individual requirements (and possibly the optional features) listed on this page, as well as the ones here, should be made with both Confluence and Calenco.
Once this is done with both products, a write-up should be done of the 'pros' and 'cons' of each product.
Based on the write-up we will make a judgement. We are then planning to use our favoured product for the purposes of authoring application help for OpenPetra.
WebHelp Output
The default WebHelp output is pretty good. What we would want to customise is exchanging of the DocBook logo with the OpenPetra logo and perhaps have some CSS tweaking done for the layout.
Optional/Bonus: Integration into OpenPetra ('F1'-Key Hookup)
TODO