|
lightdev.com |
|
Article: Single Source |
|
|
Documentation with different content and mediaDocumentation for computer software typically covers a wide range of topics. It describes how to work with an application, how it is installed, operated and maintained. Often conceptual information needs to be documented as well as information relevant for developers. A documentation about how to work with an application typically accompanies an application as online help in first place. Such online help needs to be context sensitive, i.e. the part of the documentation needs to be shown that describes the part of an application that is on the screen in the moment a user looks for help. Most of the time this documentation is required as a printed manual or at least as a document that can be opened, read and printed separate from the application in addition. Last but not least parts of the documentation are required to be available online over the internet. Without the need to download or unzip or reformat that part should ideally be readable directly inside a web browser. HTMLSpeaking of web browsers leads to HTML, the Hypertext Markup Language. HTML is a very good choice to format a document because the purpose of HTML is to describe how to show given content. In other words HTML allows to add information to document content about how that content should appear. With HTML any appearance of content can be expressed. CSSCascading Style Sheets (CSS) in addition simplify the formatting of documents. CSS can be used to define styles regardless of content. A document formatted in HTML can use a reference to a style sheet where the actual appearance is defined. This way the appearance can be adjusted centrally in the style sheet rather than inside a document. Document structureTo add an appropriate structure to a document it is required to divide it into chapters, sections, subparagraphs etc. A table of contents and an index as well as a search facility are other elements a reader expects to find the way to the information in question. While it is a good idea to document in HTML and CSS the document format is required to support more than HTML and CSS alone cover. Let us come back to this in a minute and have a look at the ideal authoring tool. Single sourceDespite the varios content and format mentioned above an author is interested to write documentation only once regardless of media or content. The ideal authoring tool would be a word processor that
A major advantage for the author would be a tool that has all the above features but keeps any technical aspect of the document format 'under the hood', i.e. details of HTML and CSS formatting should be done by the tool automatically as well as the transformation of a document structure to a storage model supporting such sructure. ConflictsComing back to what has been mentioned previously there are some drawbacks for using HTML and CSS. HTML documents are not printed easily especially when they are larger and more complex. As well a single HTML document for example can not be structured very well. A table of contents, different chapters, an index are not easily produced using plain HTML and CSS Consequently the document format needs to be more than plain HTML and the documentation tool needs to be capable to do more than plain word processing. JavaHelp to the rescueThe JavaHelp format provides an excellent solution to build and structure documentation. The name JavaHelp is misleading in this context because it suggests that Java technology is involved. When speaking of the the document format, XML Help would be a better name probably because the document format of JavaHelp is nothing else than an XML standard that is added to HTML and CSS to describe structured documents. JavaHelp on the other hand is more than only a document format specification. It is a set of tools to create and use documents in JavaHelp format utilizing Java technology. Still when focusing on the document format specified by JavaHelp it really is XML, HTML and CSS only, no Java involved. So when using the JavaHelp document format to create a documentation, an author has the best of all worlds: A document that is stored in plain text entirely, a structure that is expressed in XML entirely, a format that is expressed in HTML and CSS entirely. Simple standards rather than proprietary formats allowing for simple and open tools rather than requiring specific sofware restricting distribution and availability. Due to its open and standardized content and structure a JavaHelp document can be used in any environment whatsoever let it be online help, printed documentation, server and client based documentation, etc. Documenting in JavaHelpTo document in JavaHelp requires a tool that creates HTML and CSS content. The tool ideally works as a WYSIWYG web page editor but focusing on text documents rather than web pages. In addition to content the tools is required to support creation of structure elements such as table of content, index or search database in the same WYSIWYG / drag and drop manner while storage is done in JavaHelp format in the background. An author can write topics as in any word processor and create chapters, index entries and links with such a tool as he writes using simple drag an drop mechanisms in an easy to use user interface. Result of the authoring process are visible immediately during creation without the need to know or deal with JavaHelp or HTML specifics. JavaHelp authoring toolsThere are many authoring tools available as listed for instance on the JavaHelp product pages (see Links section below). While most tools concentrate on the JavaHelp structure and leave content authoring to separate HTML editors there are others that focus on the content side integrating all parts and trying to completely automate and hide the structural part. An implementation of a merely content focused tool is a combination of word processor, JavaHelp authoring tool and PDF converter for JavaHelp by Light Development. Application SimplyHTML is a wordprocessor entirely based on Java technology that works as similar applications for writing texts and which stores documents as HTML and CSS. The JavaHelp Plug-In for SimplyHTML adds the JavaHelp functionality in the way that an author has the look and feel of a typical JavaHelp help set with TOC and index and with the ability to edit document, TOC and index directly in the word processor just as if it was a fully editable JavaHelp viewer. Application DocAnywhere finally takes a JavaHelp help set and transforms it to PDF including all parts such as table of contents and links. Last but not least with jHelpCentral a document is made available as a server based documentation that requires nothing more than a web browser at the client side. JavaHelp documentation is seamleassly integrated with other online content this way whithout any additional effort required. An advantage of this approach is that the authoring process is very integrated so that an auhtor does not have to switch between different tools. As well the authoring process is not divided into authoring text (word processor) and building structure (JavaHelp tool). The JavaHelp structure is built automatically behind the scenes as the author creates chapters with simple drag and drop actions. The result is a document that can be used in all the various ways indicatied by this article, let it be application online help, offline help, printed documentation, server based documentation, etc. while an author has to do nothing more than to type, point and click. ExampleWith the World Holiday Calendar Light Development operates an online web application entirely based on Java which is documented in JavaHelp and PDF using the mentioned tools. The resulting help set is used as server based help and as a PDF manual at the same time. See the links section below for a live example. About the authorUlrich Hilger develops software based on more than 25 years of experience in the software industry. Under the label Light Development platform independent solutions based on Java technology are the main activity sector since 1999. Light Development products are established in many industries especially in the area of documentation and class libraries. High quality and entirely own production over the whole value chain are hallmarks of the label. Links
JavaHelp product pages:
Light Development home page:
SimplyHTML text processor based on HTML and CSS:
JavaHelp Plug-In for SimplyHTML help authoring tool:
DocAnywhere JavaHelp to PDF converter:
jHelpCentral server based documentation reader:
Example web application with server based JavaHelp: |
