[Date Prev] [Date Next] [Thread Prev] [Thread Next] Date Index Thread Index Search archive:
Date:Mon Oct 1 00:05:41 2003 
Subject:Re: help system - ideas wanted 
From:steve 
Volume-ID:1031001.01 

Hi,

Thanks to Chris, Dave, Jeff, Jonathan and Roger for answering my request for suggestions about building a help system.  I very much appreciate the time spent.  

I haven't made any decisions as yet but this is how I would summarize the views expressed.  

* My original post suggested a few more categories and Jonathan added weight to that and added the category of "wizards" which has a lot of appeal to me but probably counts as too ambitious for the foreseeable future (pity).  

* I also was thinking of a basic text format augmented by a handful of layout conventions.  Jeff argued that this was going in the wrong direction and that XML (+ XSL style processing) was a practical modern route for structured text.

* By contrast Chris argued that XML was only relevant as an intermediate machine friendly format.  Roger's remarked that the validity of this remark hinged on the effectiveness of XML editors.

* Roger suggested an alternative option of a maintaining mark-up as a completely separate "standoff" representation that "pointed into" the base text.

* Dave enquired as to the relevance of in-line code documentation as recently popularized by Java doc.  His reservation was that the in-line documentation can obscure the code.

On the last point, raised by Dave, I do have some opinions, for what that is worth.  It is an important suggestion.  The intentions behind in-line documentation are good and there have been quite a few attempts e.g. the dismal "literate programming".  Making it work well does appear to be quite tricky.

I think Dave alludes to the main problem which is that one typically wants to read documentation in parallel with code, not in-line.  That really means that you need a specialized code-editor with support for "folding".  I am glad to see that the idea of "folding" is becoming increasingly popular in all kinds of IDEs these days, a much overlooked idea, so perhaps that is a reasonable assumption.  I am uncertain about it but I am prepared to believe.

Java doc is a nice compromise solution but there are several aspects of its implementation which are rather clunky.  I find the use of a commenting convention, which is not formally defined by the language, rather distasteful.  I'm not keen on the idea of generating files via a separate compilation process, I would rather the ordinary compiler understands them, ensures consistency against the definitions, and dynamically stores the information in a (ephemeral) database.  That way it is easy to write new do
cumentation tools and much harder for code and documentation to separate - I've got far too many "disconnected" JAR files.

However, it would be quite easy to remedy these concerns with Spice.  For example, we could let the documentation be written in a completely different place (e.g. different file).

So thanks again for the thoughts.  As and when I come to any real conclusions I'll pass them on.  The main view I have come to, as a result of these suggestions, is that the content should be dynamically generated.

-- 
Steve