Structure & Content of Documents to Submit

General Rules

Language: ENGLISH
avoid non-ASCII characters or use UTF-8 encoding (in cases such as a German resource bundle)

Documents to Submit

Documentation
- Problem description / Proposal
- ReadMe File (see below for content)
- Designdocument(s)
- Description of architecture (high-level description of implementation - Documentation Guideline)
- Javadoc (API Documentation)
- Project Summary Page (HTML)
- OPTIONAL / IF APPLICABLE
  - Presentation files (PDF + Source files)
  - Seminar thesis / diploma thesis / bachelor thesis (PDF + Source files)
  - (User Manual - System description from a user point of view)
  - Test logs
  - etc.
- Formats: .txt, .html, .pdf (+ documents in their original format)
  Do not include any (hidden) helper directories as for example '.svn'
Documented source code
- Documentation Guideline
Executable program
External libraries or software if necessary
(Example) data files

Directory Structure for Documents

directory	content
/	readme.txt (content see below)
/src	source code
/lib	external libraries (e.g., .jar files of toolkits or other external libraries)
/bin	directly executable (compiled) program (e.g., executable .jar file) + necessary libraries
/doc	project documentation (problem description, description of architecture, thesis, presentations, etc.) allowed formats: .html, .txt, .pdf (+ files in their original source format in the directory /doc/source -- e.g., .doc, .ppt, LaTeX)
/javadoc	source code documentation (javadoc)
/data	(example) data files
/html	project summary page (HTML short summary)

Readme File

A text file called readme.txt has to be provided in the root directory that contains the following:

project title
author(s)
date
which toolkits / external libraries are being used (including version & license information)
in which environment the development was done (e.g., JDK x.y, Windows x.y, Eclipse y.z, Database y, etc.)
information on how to start the program
name of executable program files (.jar)
command line parameters
configuration files & settings

Executable Program Files

The executable version of your project is to be put into the /bin directory (directly executable .jar file). To include external libraries they either need to be copied in the /bin directory as well (--> /bin/lib) or be packaged inside the .jar. Furthermore, a manifest file needs to be created (that sets the "Main-Class" and "Class-Path" paramters).

Example of a Manifest File:

Main-Class: at.ac.tuwien.cs.ztimeview.ui.zTimeView
Class-Path: lib/piccolo.jar lib/piccolox.jar lib/mpxj.jar lib/jakarta-poi-2.5.jar .
Created-By: Wolfgang Aigner

Note that many IDEs are capable of generating executable .jar packages (without the need to manually create them as described above).

Project Summary Page (HTML short summary)

Contents:

Short Title
Full Title
Team (+indicating contact person)
Description
Images
Downloads
Publications
Related Work
Alternative Webpages
Funding

List of Examples

Download page template (.zip)

Misc

JAR - Java Archive

Using JAR Files: The Basics JAR Tutorial by Sun
Distributing your Application as an executable JAR file
Fat Jar Eclipse Plug-In Eclipse plug-in that generates an executable .jar file

ANT - Java-Based Build Tool

"Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles."

To automate the build process, using ANT is advisable (instead of proprietary batch files, make files, etc.). The advantage of ANT is that it is Java-based and configured via XML files, i.e., it is platform-independent.

The Apache ANT Project Webpage
Automate your build process using Java and Ant good introduction, but not up-to-date
Fleißige Ameise - Ant: Make-Alternative für Java German article by Michael Marr

JUnit - Automated Unit Tests in Java

JUnit is a very useful tool to automate testing of Java classes. Among other things it is integral part of the eXtreme Programming development process.