Tool to Create Annotated Directory Structure Documentation

Question

I've got a moderately complicated application that has been developed primarily by me, and I'm getting ready to bring a few more developers in, and I'm thinking of various forms of documentation that might be helpful.

I want to communicate information about the directory structure/layout of the project so the new guys will know where to look for things when they are getting started and as they add features, know where to put new files etc., so we can keep things organized and consistent.

Is there any tool out there can create something a little more sophisticated than just a plain text document? I'm thinking of something that looks similar to Windows Explorer with a directory structure on the left in a panel and then when you click on a particular folder, you would be able to view some text or HTML that describes the folder in the right hand panel.

Oh, and development will be done on Windows, but cross platform would be nice.

Answer 1

You didn't mention the programming languages used, but Doxygen is fairly powerful and configurable, it can also be used to embed URLs or files.

Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.

It can help you in three ways:

1. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in $\mbox{\LaTeX}$) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
2. You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. You can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
3. You can even `abuse' doxygen for creating normal documentation (as I did for this manual).

See the Doxygen Manual for more information, specifically you will want to look into the autolink support which allows you to reference arbitrary URLs and file names, so that you can easily refer to standard files stored in each subdirectory (DESCRIPTION, README, TODO, BUGS, AUTHORS):

Links to files.

All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file.

Also, the output of Doxygen can be similarly customized: http://www.stack.nl/~dimitri/doxygen/customize.html

Answer 2

I'm happy with dokuwiki