• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Format for Design Documentation

 
Greenhorn
Posts: 28
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
According to my copy of the Submission Instructions, a (single) plain ASCII-format README.TXT file must be included with my submission. This README.TXT file, amoung other things, must identify "what file(s) contain(s) a detailed description of your design choices and other supporting documentation."
My question is this: What format should my design choices documentation be in? Should this documentation also be in plain ASCII format, or can I use HTML?
I'd like to submit my design docs using a set of linked HTML documents & .gif files so I can include some simple diagrams which help to explain my design. Has anyone else tried this, or heard of anyone getting the full documentation points while submitting their design docs in HTML format?
Along similar lines, I'd like to submit my user documentation in HTML format too. I still intend on providing my README.TXT file, which will reference my HTML docs, in plain ASCII format.
 
Ranch Hand
Posts: 334
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I understand that the README.txt - basic user documentation must be plain text (by Notepade) and documentation for classes of the completed project in HTML vreated by javadoc.
But, the format of the design-choices is unspecified in which format.
In my assignment, it states that " Design decisions should be briefly but clearly described in your comments."
I do not understand how you can describe your design chioce in your comments. Are the comments placed within codes or in a document ?
Please comments,
Ruilin
 
Emerson Dunne
Greenhorn
Posts: 28
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
>basic user documentation must be plain text
My assignment instructions says the "user documentation may be online if you wish, but there must be one file in the root directory of your submission called README".
Since the User doc can be online, I'm going to assume that providing the user doc in HTML is acceptable (even though I don't plan on using the HTML for online help in my apps).
I have decided to provide the following:
1. README.TXT - which is in plain ASCII and contains details requested by my assignment's instructions.
2. javadoc with package-level docs
3. User Manuals in HTML
4. Design Doc in HTML
My source files contain a few javadoc comments related to design decisions, but only to help explain complex code. My HTML design doc is what I will expect the grader to use when evaluating my
project submission.
 
reply
    Bookmark Topic Watch Topic
  • New Topic