NX: Bodgitt & Scarper: Documentation Format

[YH Lai]

Is there got any format structure for version.txt, user guide.txt and choices.txt need to follow? Or is there got any guideline to write it? Thanks

[S Perreault]

My question has to do if we use returns in the textfile or just let each paragraph continue to the right as one long line?

[Andrew Monkhouse]

Hi YH & S

The contents of the version.txt file is described in the instructions you received.

There are multiple formats your help file can be in - refer to your instructions on what is allowable. As for the contents: think about what you need in order for someone to start your application in it's various modes, and use the application.

As mentioned in another thread earlier this week, a good rule of thumb is to write the instructions, then give the instructions and your finished application to some person who fits the "end user" category, and see if they can use your application correctly. (So give it to your partner, and see if they can run the application in all its modes). If they can, then your instructions are probably fine .

The choices.txt file should be written as you are developing your assignment, not afterwards. Whenever you make a major design decision, you should make a note of it in your choices.txt file. If you do it that way, it becomes easy to write such a document. Trying to remember what choices you made after you have completed the document can be rather difficult. I would recommend something simple: a heading for the choice, with bullet points for your reasons. E.g.:

I chose RMI versus Serialized Objects over Sockets because

I got "heads" when I flipped a coin

RMI is shorter to write

(Of course, you may prefer to think of better reasons )

Sun do not want a huge document - just something to show that you are aware that there are alternatives to some of your choices, and something that they can use in the exam to validate that you wrote the assignment .

I think using bullet points results in a shorter document, and can be easier to replicate in the exam (especially for candidates for whom English is not their first language).

I did all my documentation as HTML files, so I did not need to worry about word wrapping. But if I was using plain text files, I would manually wrap files myself, probably about column 76 rather than relying on the examiner setting word wrapping in their editor. This is my personal choice - I am sure that there are plenty of people who would advocate the opposite .

Regards, Andrew

[Andrew Monkhouse]

Hi YH & S,

If you would like to see some examples of topic headings for choices.txt files for the older assignments, you can look at My Design Choices. I would recommend people use far less than that in their choices.txt file though.

Regards, Andrew

[YH Lai]

Thanks, this is very helpful to me

[S Perreault]

Andrew,

Thank you. I think I will use .html format to ease my mind about line wrapping =) EDIT My instructions do not allow html format for the choices.txt :-/

Also, I probably should have written all of the decisions in one file, I am not that organized and now have about 15 pieces of paper with scribblings on them 8)

Perogi.
[ June 18, 2004: Message edited by: S Perreault ]