File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Agile and Other Processes and the fly likes Software documentation management Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Software documentation management" Watch "Software documentation management" New topic
Author

Software documentation management

Peter Braun
Ranch Hand

Joined: Feb 09, 2005
Posts: 57
Hello,

I couldn't find a better subject for my question?

I would like to ask that, in real projects, how do you manage documentation of software projects? I mean how various artifacts, docs, UML diagrams, models, etc. What is the good practice for that? A web-based tool or something?

Thanks in advance,
Peter
Scott Ambler
author
Ranch Hand

Joined: Dec 12, 2003
Posts: 608
You might find Agile Documentation and Single Source Information to provide some insight.

Good starting points:
1. You need a lot less documentation than you think.
2. There should be a clear purpose and audience for the document, otherwise don't create it.
3. If it's worth creating, it's worth putting under CM control.
4. The less documentation you create, the less you have to manage.
5. There is no correlation between documentation and software development success. There is a very clear correlation between documentation and bureaucracy.
6. Use the Simplest Tools.

- Scott


<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Don Morgan
Ranch Hand

Joined: Jul 24, 2003
Posts: 84
The documents need to be managed just like any other artifact, using whatever configuration management system/process you are using.

There are some options for making them available to users, some of whom may need write access. These options are listed below in order from what I think is the lightest approach to the heaviest:

1. shared drive or folder
2. simple web pages
3. wiki
4. document management system, like Sharepoint from Microsoft

Probably the most common method of distributing documents is simply to email them as attachments.

Base your decision on the requirements for documentation, the audience and the skill set of the people creating them.
[ February 09, 2006: Message edited by: Don Morgan ]

Don Morgan, Founder
www.DeveloperAdvantage.com - FREE Audiobooks for Software Developers
Gerardo Tasistro
Ranch Hand

Joined: Feb 08, 2005
Posts: 362
I use JavaDoc which creates HTML documentation. I have Poseidon as an UML tool which also exports documentation to HTML. Web based documentation is the best since you can easily distribute and keep sincronized.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Software documentation management