Java Project Documentation

Question

I need to document a Java project. I am a C# Programmer and Systems Analyst. But I am new to Java.

I have the directories checked out of SVN.

These directories include the source directories, WEB-INF and other files required for definition of the project, classpath etc.

I understand that the files essentially belong either of the following three categories

1. Source code files / directories that are based on the way the packages are structured (.Java)
2. Directories / Files required for project definition, compiler settings etc
3. Files required for deployment.

The project is (as most Java projects are) an Eclipse based project designed to be hosted on Tomcat.

Now, give the above information I have decided to document the entire project into three different documents

1. A document explaining the source code etc.
2. A document explaining the purpose of the files & directories that are required for compiler settings, project definitions etc
3. A document that explains the deployment directory structure.

Or alternatively I could create a single document with three sections that explain 1-3 above.

Now, questions

1. Is this the right approach?
2. Are there any other methodologies that I can follow or borrow from?
3. Are there any other suggestions etc that you can add to this approach

Any additional info will be of use.

Thanks a ton in advance

Answer 1

I think you're on the right track. In a project you need to address three documentation needs

1. User Documentation This include a document stating what the application is about, and how to start it/access ut.

2. Development Documentation This includes at least the Javadocs, a description of the source code directory structure, the build process (ie, how to compile the project), compiler time dependencies, development standards, how to set up a database for development, and how to get the source code from the repository. These are the minimum you need to get others to work in your project. Additionally as the project complexity grows I like to put together a series of "How To" for common tasks in the system (ie: "How to leave an Audit Trail for a given Operation", "How to use the Logging framework", "How to manage exceptions", etc), a description of the main Domain classes and their relationship. If you use a database, and the database schema is not exactly one-on-one with the domain classes, I'll add a schema documentation.

3. Deployment Documentation This is basically the installation manual of the application, describing any steps needed to make it run: putting the WAR in Tomcat, running scripts against a database, configuration files that needs to be modified, etc,etc.

As you see, you already partially addressed two of them. Start small and simple, and add the rest as the need arises.

It also helps to check if your organization has any documentation standard.

Answer 2

Try Javadocs link. Written with proper planning, it will address all your points above.