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
|