[CONF] Apache OpenOffice Community > Application Help

[Kay Schenk (Confluence)]

Application Help Page edited by Kay Schenk Changes (8) ... h2. Current Situation and Issues h3. Structure At present, the application help files are located in the source code module _helpcontent2_ with the following structure: ... The biggest module is "shared" that takes all content that is valid for more than one application (which is most of the content) in order to make it available to the help viewer in all applications. But this leads to awkward side effects when content is valid for more than one but not all applications, yet it is still available for all applications. This leads to situations where the users finds content that is actually not in scope for his/her current context (but still visible since in shared) which can be pretty confusing. h3. Implementation with the application The *help viewer* is a Writer/Web component wrapped in a -nice- UI and served by the help content provider. The appearance of the help UI is completely outdated, and so are its concepts (to separate between TOC, Index, Search, for example), and the fact that it's just a Writer document window in disguise can lead to all sorts of -funny- nasty side-effects. Also, the Writer/Web component has a hard time even displaying HTML 3.2 correctly, so the help files breathe the spirit of 1985. The full text search does not work correctly and never has. h3. UI Issues The content and structure of the help files do not show a clear distinction between referential, conceptual and instructional information. On looking for guidance, users can stumble over files that just list the UI elements of a dialog with one explanatory sentence but with no indication of the context. h3. Maintenance Issues h2. Moving Forward * A rather complicated architecture (understatement!) in terms of maintenance. The only found document describing what's going on in any detail can be found at: [Understanding and Authoring OpenOffice2.0Online Help|http://www.openoffice.org/documentation/online_help/OOo2HelpAuthoring.pdf]. This is a cumbersome document which doesn't directly explain how to assign new ids to help items, where to put them etc., given the hierarchical nature of the help system. * New volunteers desiring to get involved with authoring or changing any help item would likely need to install the "Help Authoring" extension, which can be found at: [http://people.apache.org/~jsc/test/helpauthoring.oxt]. Once this extension is installed, adding or changing help texts is a bit easier but followup maintenance using Perl scripts found in the repository are needed for adding new help texts. * Since current help system is stored *within* the source repository, anyone needing to make changes must be a project committer. This seems rather burdensome to new volunteers who would like to participate in this area. * Because the Online Help is "homegrown" and difficult to fathom, it will always need special attention. So, it is not very sustainable in its current form. h2. Moving Forward Since we're off to a fresh start, this is what we ought to do with the help: (see also the following mail thread: [http://markmail.org/message/tl5lsy4cxaa3s6lx]) ... Full Content This is the planning page for the OO application help (aka online help, despite not being "online"). Current Situation and Issues Structure At present, the application help files are located in the source code module helpcontent2 with the following structure: helpcontent2 helpers these are required or helpful for building the help content, some files are called by make, some others are obsolete xmlhelp.dtd > the DTD for the help XML format source this is the actual content auxiliary this are help relevant files that are not content *.tree > the definition files for the help viewer table of content *.xsl > transformation scripts used to process the help files $LANG/*.css language dependent files for controlling the HTML output $LANG/*.cfg language dependent config files (legacy) text the help content files, organized by modules (rather awkwardly, see below) The help content files are in a home-grown XML format described in helpers/xmlhelp.dtd and are processed in various ways when the help is being built: when non-English versions are built, the English content inside the help files is replaced by the localized content stored in a different module. the help files are XSL-processed to produce the full text search index the help files are XSL-processed to extract the extended tips displayed in the UI the help files are XSL-processed to extract the keyword index The final help set consists of sets of various files (jar, cfg, tree, xslt, database files) for each module. A module in the help does not exactly correspond to an application module (Writer, Calc, Impress) for historical and technical reasons. The schart module is present in the help although there is no standalone Chart application. There is no sdatabase module, although there is a Database application. So: it's a mess. The biggest module is "shared" that takes all content that is valid for more than one application (which is most of the content) in order to make it available to the help viewer in all applications. But this leads to awkward side effects when content is valid for more than one but not all applications, yet it is still available for all applications. This leads to situations where the users finds content that is actually not in scope for his/her current context (but still visible since in shared) which can be pretty confusing. Implementation with the application The help viewer is a Writer/Web component wrapped in a nice UI and served by the help content provider. The appearance of the help UI is completely outdated, and so are its concepts (to separate between TOC, Index, Search, for example), and the fact that it's just a Writer document window in disguise can lead to all sorts of funny nasty side-effects. Also, the Writer/Web component has a hard time even displaying HTML 3.2 correctly, so the help files breathe the spirit of 1985. The full text search does not work correctly and never has. UI Issues The content and structure of the help files do not show a clear distinction between referential, conceptual and instructional information. On looking for guidance, users can stumble over files that just list the UI elements of a dialog with one explanatory sentence but with no indication of the context. Maintenance Issues A rather complicated architecture (understatement!) in terms of maintenance. The only found document describing what's going on in any detail can be found at: Understanding and Authoring OpenOffice2.0Online Help. This is a cumbersome document which doesn't directly explain how to assign new ids to help items, where to put them etc., given the hierarchical nature of the help system. New volunteers desiring to get involved with authoring or changing any help item would likely need to install the "Help Authoring" extension, which can be found at: http://people.apache.org/~jsc/test/helpauthoring.oxt. Once this extension is installed, adding or changing help texts is a bit easier but followup maintenance using Perl scripts found in the repository are needed for adding new help texts. Since current help system is stored within the source repository, anyone needing to make changes must be a project committer. This seems rather burdensome to new volunteers who would like to participate in this area. Because the Online Help is "homegrown" and difficult to fathom, it will always need special attention. So, it is not very sustainable in its current form. Moving Forward Since we're off to a fresh start, this is what we ought to do with the help: (see also the following mail thread: http://markmail.org/message/tl5lsy4cxaa3s6lx) Help File Source Format move to a standard format (DITA was proposed) simplify the build process create an easy authoring workflow to enable participation Help Viewer use current technology (HTML 4+, CSS4, bells and whistles) don't let the user decide on which route to find info (TOC, index, search), give a search input field and let the help find the best results fix the search engine integrate the help viewer with the UI Help Content and Structure Limit help content to instructions, and some basic concepts Show reference information ("enter your name in this field") where it's needed, on the UI, side-by-side to the element it refers to. For that, we need rich fornatting in "bubbles" (extended tips). Reduce the amount of offline help content and allow to expand to online sources Allow rich media in help files Stop watching space | Change email notification preferences View Online | View Changes