A documentation system? A goal for the next couple of days.

Since active coding (other than basic fix-er-ups) is on hiatus while Dr. M and our Regressions Guy (it’s funny when you go to a school so small that there’s a single person in the Math Dept. that is an expert on regression analysis) attempt to isolate a method to estimate the error with the model we’re using, I’m hitting the documentation hella hard until a solution is reached. I want it to be as near iron-clad as I can get it.

I’m at something of an impasse, however–how do people write documentation systems? Obviously, I can create a user’s guide and a developer’s guide in HTML (or maybe using a system like TeXinfo would be in my best interests, for the versatility of formats) and include them with the JAR that will be my program. There will be Javadoc files as a starter for other developers (or just me). But how in tarnation to I make a live, “online” (accessible from within the program) help system? Do I just want to make a webpage that displays when the user clicks “help”, and add in “context sensitive” help through links to direct sections? Are there systems for this, something I can pull into my Java app and modify to work for my purposes? I have no idea how this type of thing is done.

So today’s goal (among other things) will be to determine how such systems are created without relying on “native” systems, like the built-in help system Windows provides. I can’t assume such things will exist where this program will be used; who knows what systems they’ll be running on the base Dr. M and Jenn will be inhabiting in Antartica this winter? And I am certainly keeping my ass in Linux until newspaper work requires me to do otherwise, which is further incentive.

One Comment

  • stobor


    I guees Ive started reading your blog regularly now.
    As far as help systems go, I know I have been usually very dissapointed by the HTML type that you pull up in a browser.
    However, HTML is a good way to markup and link your docs together. Maybe Java has a built-in library for displaying HTML that you could build into the app somehow.
    Something kind of cool would be some kind of system that could provide help on any button or object. (Would be kinda cool to make your own controls that override the swing controls and put an underlined question mark [like on websites…] after every object. Have these link into the help system.

    If something like this doesn’t exist, I dont think it would be incredibly difficult to devise.

    …just my $0.02, shoot me an email if I didn;t make any sense.