NX: URLy Bird 1.3.1 Documentation

[Bharat Ruparel]

Things have definitely become less interesting. The dreaded documentation time!
Any ideas on how long should the User's Guide (userguide.txt) and choices.txt documents can be? Or a better question should be?
Since these are supposed to be plain ASCII text files, can the screen shots be included?
Any ideas on how to organize them and write them?
Look forward to your thoughts/ideas/suggestions.
Regards.
Bharat

[Jim Yingst]

Things have definitely become less interesting. The dreaded documentation time!
I share your pain, borther Bharat!
Any ideas on how long should the User's Guide (userguide.txt) and choices.txt documents can be? Or a better question should be?
I'm not the person to ask here; I keep rambling in mine and then trying to cut it back to something manageable.
Since these are supposed to be plain ASCII text files, can the screen shots be included?
I'd say no, there's no reasonable way to include this in an ascii file. But for the user guide, consider HTML instead if your instructions allow that option; this need not be complex, but offers more options, including images. You can even make an online help system out of it by making a simple HTML browser using JEditPane, to allow the user to look at the user manual while running the program. (Have to include HTML in runme.jar to make sure the program can find it though.) Not necessary of course, but kind of fun, and doing it in HTML makes things about as easy to modify as you can reasonably expect for an onlne help system, IMO.
As for the decisions.txt, no images there. But if you have a burning desire to show UML diagrams or something, you might be able to work them into the javadoc, since that's HTML.

[Andrew Monkhouse]

Hi Bharat

Originally posted by Bharat Ruparel:
Things have definitely become less interesting. The dreaded documentation time!

Strangely enough I normally enjoy documentation - at least when it is proper documentation: user documentation, system documentation etc.
But I left documenting my project until the end, by which time I was sick of the whole project. So I didn't enjoy it.

Originally posted by Bharat Ruparel:
Any ideas on how long should the User's Guide (userguide.txt) and choices.txt documents can be? Or a better question should be?

Like Jim, I overdid my documentation.
You might be interested in this thread where Patrick Cobbett was kind enough to share Sun's response when he asked them how much to write.

Originally posted by Bharat Ruparel:
Since these are supposed to be plain ASCII text files, can the screen shots be included?

I think your choices.txt file must be in plain text format: so no screen shots.
I like Jim's suggestion that UML could go into the javadoc. I would probably suggest having it in the package level documentation - javadoc already has a standard mechanism for copying the HTML and graphic files from the source directories into the created API documentation.
Alternatively, as well as the choices.txt file, I think you could also have a separate HTML file (or files) for anything you want to describe graphically (e.g. UML documents), and just make a reference to it in your choices.txt file. Just make sure that everything that should be in the choices.txt file is really there - the html file would only be for suplemenatry information which the examiner can look at if they want to.
As for the user guide: as Jim suggested, check your instructions. Mine says: "you must provide either a single plain ASCII (not word processor format) text document, which must be called userguide.txt, or multiple HTML files which must all be accessible from a starting point document that must be called userguide.html". Since you are allowed HTML, you can include graphics if you like.

Originally posted by Bharat Ruparel:
Any ideas on how to organize them and write them?

Choices.txt should be written as you are developing your project. Everytime you make a design decision, put a note into the choices.txt file. If you havent done that, then I suggest you start by reviewing your code - see if you can spot anywhere where you made an obvious decision. One way of spoting it is to see if you can remember where you rewrote some section of code - obviously you made a decision that the old thing was wrong, and the new way is better. After you have done that, look through your posts here in JavaRanch - see if there are posts where you advocated certain designs and (especially) argued against other designs: these could possibly be your design decisions as well. (The reason I suggest looking at JavaRanch after your code review is that if you change the order, it will be more tempting to skip sections of your code review because you think you covered it in a JavaRanch post).
As for the user guide: I would (and did) have a section describing how to start the application (assume dumb end user who has never seen a Java program / booking software before - don't assume an examiner who has seen it 100 times). Then a quick description of how to use the various screens that you have.
Regards, Andrew
PS: When writing your choices.txt file, try and avoid the temptation of stating your reason for a design as "Phil doesnt like it"
[ October 19, 2003: Message edited by: Andrew Monkhouse ]

[Bharat Ruparel]

Hello Andrew/Jim,
Thanks for your responses. One thing I am a bit apprehensive about is the readme.txt file being mentioned on the forum. My instructions do not require a readme.txt file! Instead, they ask for the following documents:
1. A file called version.txt that contains pure ASCII (not a word processor format) indicating the exact version of JDK you used, and the host platform you worked on.
2. A file called choices.txt that containing pure ASCII(not a word processor format) text describing the significant design choices you made. Detail the problems you perceived, the issues surrounding them, your value judgments, and the decisions that you made. This document should also describe any uncertainities you had regarding the project, and the decisions you made while resolving them.
3. User documentation for the database server and the gui client. If your user documentation is online then you may omit this file. However, if the documentation is not online, you must provide either a single plain ASCII(not word processor format) text document, which must be called userguide.txt, or multiple HTML files which must all be accessible from a starting point document that must be called userguide.html.
These are my instructions. I did a search for readme.txt in my instructions.html which was unsuccessful in finding it.
Just forget about it?
Look forward to your response(s)
Regards.
Bharat

[Andrew Monkhouse]

Hi Bharat,
The Fly By Night Services assignment required a README.txt file (Sun's capitalization, specified in the instructions twice!).
Since it is not listed in the new assignments, don't worry about it.
Most of what was in the README.txt file is either already covered in the documents you are writing, or just doesnt apply for the new assignments.
Regards, Andrew

[Philippe Maquet]

Hi Bharat,

Things have definitely become less interesting. The dreaded documentation time!

I'd be happy in your place !
I have very similar instructions as yours as far documentation is concerned (URLyBird 1.2.1). Like Jim and Andrew, I would suggest you to choose the HTML format for the user guide if you want to include screen shots (good idea IMO).
Unfortunately, I didn't encounter yet the documentation issue. But I'll tell you here what I think I'll do when it happens.
For the user guide, I like the solution of "multiple HTML files which must all be accessible from a starting point document that must be called userguide.html." :

It's better than userguide.txt because of the screen shots you may include.

It's better than "If your user documentation is online then you may omit this file" solution, because - as we don't have any readme.txt file - how to explain how to start the application then ? (In the very first lines of userguide.html, I'd explain how to start the application in its different supported modes.)

It's easy to combine an external HTML help system with the "online" help system they mention. I think that's what Andrew did.

Our version.txt should only be two lines long as our instructions indirectly suggest.
Now as far as choices.txt is concerned :

A file called choices.txt that containing pure ASCII(not a word processor format) text describing the significant design choices you made. Detail the problems you perceived, the issues surrounding them, your value judgments, and the decisions that you made. This document should also describe any uncertainties you had regarding the project, and the decisions you made while resolving them.

I do think it should be short (a few pages). Don't forget that the biggest part of the grader's reading should be your sources ! choices.txt should be written with that in mind : "how to make the grader eager to dig into my sources and its javadocs, hopefully in the best parts of them ?".
The significant design choices we made concern the network and database parts IMO (for the GUI parts we don't make any choice, we just follow - hopefully - swing best practices).
The main choice you did in the network area is choosing RMI over sockets. Just tell it and say why (a few lines IMO). As RMI is a well-known "closed" technology (comparable with swing in that aspect), you'll probably not have much more to tell. For people like me who chose sockets, there is a little more to write, but it should be written in maximum one page IMO.
In the database area, there is probably much more to write. Why did you choose to

use NIO (or not) ?

cache the records (or not) ?

cache all records or part of them ?

consider it as one flat file to be accessed in this context or as a multi-table reusable database ?

handle the charset the way you did (hardcoded ? replaceable ? how ?)

handle deadlock situations or not ? allow multiple locks to be granted per client, or not ?

...

All those questions turn around performance, scalability, and reusability. As none of those words appear in our instructions, any choice may be defendable !
Many uncertainties have been discussed here on the forum. The main ones from memory are :

the 48 hours range (the decision is to take it into account or not)

which records to display ao the user : "bookable" records or all records

the DuplicateKeyException issue

the way IOExceptions should be handled (wrapped in RuntimeExceptions or in existing checked exception ?)

I don't think it's the less interesting part you're facing now. It could be the more rewarding one, because it's the one you get just before the big reward !
Good luck,
Phil.

[Bharat Ruparel]

Thanks Andrew & Phil.
Regards.
Bharat
[ October 20, 2003: Message edited by: Bharat Ruparel ]

[Philippe Maquet]

Hi Bharat,
I don't how/when/if I'll finish and upload my own assignment (to finish it, I should be working on it what I currently cannot).
When Andrew wrote :

But I left documenting my project until the end, by which time I was sick of the whole project. So I didn't enjoy it.

,
I thought, "if I could have coded the whole project before I got sick of it, I would be happy.".
Now as I mentioned a few design-choices subjects in my previous post, while writing "any choice" may be defendable, I am willing to enter in any discussion about any design choice anybody would feel weak in his/her opinion. The more I've been working on this project the more I feel in the right mood to defend the simplest choices. Mark, it's sunny outside, isnt'it ?
Best,
Phil.

[Bharat Ruparel]

Andrew/Jim/Phil,
Any tools that you can recommend for writing HTML documentation? I have Microsoft FrontPage, will that work?
Regards.
Bharat

[Philippe Maquet]

Hi Bharat,

Any tools that you can recommend for writing HTML documentation? I have Microsoft FrontPage, will that work?

Microsoft FrontPage should do the job, but I'll use Microsoft NotePad : it's free, lightweight, bugs-free, ...
Seriously, I would keep it simple : a few html files + (maybe) a css file to make them look "nice" should be enough, anyway something simple enough to typed in any basic text editor.
Best,
Phil.
[ October 20, 2003: Message edited by: Philippe Maquet ]

[Jim Yingst]

I haven't used FrontPage in a long time; it was always generating extra tags which were horribly overcomplex, and often just plain wrong. I too am using a simple text editor. Actually I'm writing most of the docs as plain text initially, and will convert to HTML later. (Formatting is the last thing I want to do.) I agree with Philippe that it's good to keep the HTML very simple for this assignment.

[Philippe Maquet]

Hi Bharat,
Just a few more words to tell you that I fully agree with Andrew's last PS :

Andrew:
PS: When writing your choices.txt file, try and avoid the temptation of stating your reason for a design as "Phil doesnt like it"

There are a number of good justifications of Andrew's advice :

Nobody at Sun knows me yet and hopefully Sun's guy out there don't read our posts.

Even when/if they'll know me, it is not desirable IMO to emphasize in your choices.txt file that you made a bad decision on a given design

By bad luck, it could happen that your grader is named Phil ...

Best,
Phil.

[Jim Yingst]

However, for purposes of discussion here at JavaRanch, many of us would consider "Phil doesn't like it" as ample justification for any design choice you may feel like.

[Philippe Maquet]

You'd be surprised to know how often I think likewise myself ...
[ October 21, 2003: Message edited by: Philippe Maquet ]