The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Where to put software documents?

I am a team lead trying to get my group to start doing up front design and produce some simple design documents.  Right now we have some problem statements, use cases, activity diagrams, and sequence and class diagrams.

The question I have is where to put these items? If I am looking at a source file, where should I go to find the associated design documents such as a class diagram; similarly, if I am looking at a high-level module where should I go to find the multi-submodule related use cases or sequence diagram?

I want pseudo-software types to be able to find high level diagrams easily, but I also want developers to have documentation and code in close proximity for maintainability. 

I see a lot of discussion out there about how to create these artifacts, but I haven't found anything useful for how a fair sized project keeps and version controls these things.
Bryan Send private email
Monday, October 22, 2007
The best is to use a nice wiki (such as Confluence) and generated reports. Using a wiki (versus checking in documents) removes the barrier for people to actually document the system and update it easily. People will sometimes add modelling diagrams, though usually only at the highest level, to express the system. The rest can be auto-generated during the build process and deployed with the rest of your application.

Its also quite nice if the code is extremely friendly to others, by making it a joy to read and well componentized (both at the class and package level). Most developers just want to dig in and will go to the real documentation only for non-code related information or if the code is too difficult to understand by itself. Most of the time I've found class/sequence/etc diagrams as being only useful for managers to understand the system, since they won't look at the code itself, versus being an aid for other developers.
Benjamin Manes Send private email
Monday, October 22, 2007
+1 for a wiki-like repository

We use Alfresco ( but any Wiki/CMS should work.

The 'trick' is to spend some time thinking about who is going to provide or access the documentation and what organization form makes sense. For example, are you organized by division or project? Do you organize your documentation by release or function first? This will let you set up a hierarchy that makes sense for people providing or accessing the data.
Just A Guy Send private email
Tuesday, October 23, 2007
The round filing cabinet hasn't failed me yet.
my name is here
Tuesday, October 23, 2007
How about in source control,
with the source for change control.
EvilTeach Send private email
Wednesday, October 24, 2007
Why WOULDN'T you version control your documents just like with source code?

I use Maven to build my projects, so it's pretty easy to generate a full web site for each project from APT(**) documents within a repository.

** APT stands for "Almost Plain Text" and is a wiki-like mark-up format in widespread use at Apache.  In addition to creating HTML, it can create a host of other formats (including PDF).
Steve Moyer Send private email
Wednesday, October 24, 2007
+ version control

It is critical to have formal specs under version control and issued after review so that you never get that 'programmer working to the wrong spec' issue.

We have all our specification documents in a tree structures in VSS. One high-level functional specification could relate to several different bits of software written in different languages by different team, so at functional spec or use-case level it does *not* belong with source.

Source code is documented in source code (comments) and programmer generated documentation resides at the level it is found parallel to the source - often in .txt files.

None of this precludes other documentation like Wiki's or machine generated HTML for the source code, but as a software designer that is not my concern so much as higher level functional & technical specs that should not be linked to source at all; source code changes with implementation & debugging, functional requirements don't.
Grant Black Send private email
Monday, November 12, 2007

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz