Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes NX: Bodgitt & Scarper: Documentation Format Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "NX: Bodgitt & Scarper: Documentation Format" Watch "NX: Bodgitt & Scarper: Documentation Format" New topic
Author

NX: Bodgitt & Scarper: Documentation Format

YH Lai
Greenhorn

Joined: Apr 15, 2004
Posts: 16
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
Ranch Hand

Joined: Oct 29, 2003
Posts: 37
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
author and jackaroo
Marshal Commander

Joined: Mar 28, 2003
Posts: 11405
    
  81

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


    The Sun Certified Java Developer Exam with J2SE 5: paper version from Amazon, PDF from Apress, Online reference: Books 24x7 Personal blog
    Andrew Monkhouse
    author and jackaroo
    Marshal Commander

    Joined: Mar 28, 2003
    Posts: 11405
        
      81

    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
    Greenhorn

    Joined: Apr 15, 2004
    Posts: 16
    Thanks, this is very helpful to me
    S Perreault
    Ranch Hand

    Joined: Oct 29, 2003
    Posts: 37
    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 ]
     
    I agree. Here's the link: http://aspose.com/file-tools
     
    subject: NX: Bodgitt & Scarper: Documentation Format
     
    Similar Threads
    how to convert the decimal degree format to degree minutes format of latitude and longitude?
    is SCBCD Mikali notes available in pdf format
    run dos commands through servlet
    Printing PDF/HTML in Java
    Recording in au format ??