Genii Weblog

Documentation in PDF vs. database

Thu 21 Jul 2005, 04:05 PM



by Ben Langhinrichs
I have been thinking about the difference between documentation for products in PDF (or Word or WordPro) versus documentation in a Notes database.  There are advantages to each.  Documentation in a PDF document can be easily printed or downloaded.  Document is a Notes database can be more easily categorized in different ways.  I had just about decided that our product solutions, such as CoexLinks and CoexEdit, should be documented solely in PDF/Word format, and our product tools, such as the Midas Rich Text LSX, Midas Rich Text C++ API and @Midas Formulas, would have databases (actually, they share one database) to allow separate handling for each class or method.

But, here we are, about to release CoexEdit 1.1, and already I am not so sure.  CoexLinks works fairly well with a PDF/Word document, and CoexEdit is installed the same way, and each solves a single problem in a simple, elegant way, so I thought they would be more similar.  What I forgot was how complex the web, and the web editors, can be.  CoexEdit needs documentation on more than installation.  It needs troubleshooting that has nothing to do with CoexEdit as software, but rather has to do with the web editor the developer is installing.  Since the developer thinks of that as going along with CoexEdit, and since CoexEdit won't work unless the web editor is installed properly, there are lots of little things to document, and there will be increasing numbers as we add direct support for more editors.

So, I am building a CoexEdit Help database.  It shares a basic design with the Midas Help database, but the content is fairly different.  There are some basic configuration technotes, release notes as issues are fixed and enhancements made, and then room for lots of growth in the web editor area.  Now, if only my daughter were not off working in college, she could help me write all this.  Sigh!

Copyright © 2005 Genii Software Ltd.

What has been said:


340.1. Stephan H. Wissel (24/07/2005 09:01)

Could "either/or" be the wrong question? You could use the Notes Database as foundation for all documentation and then add some XSL/FO magic to render this into a pretty PDF manual.

If the RichText is very beasty to transform (some first tries can be found here: http://www.jnotes.de/JNotes/jnotes_webware.nsf/jnotes/Tools_RTFtoPDF.html -- you might need Babelfish) you should talk to the guys who make CoexEdit, since HTML -> XSL:FO has been solved quite often .

My 2c

;-) stw