A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.
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.
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.
Monday, October 22, 2007
+1 for a wiki-like repository
We use Alfresco (http://www.alfresco.com) 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.
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).
+ 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.
This topic is archived. No further replies will be accepted.Other recent topics
Powered by FogBugz