File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
Win a copy of Clojure in Action this week in the Clojure forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Software documentation management

 
Peter Braun
Ranch Hand
Posts: 57
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 608
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Don Morgan
Ranch Hand
Posts: 84
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 ]
 
Gerardo Tasistro
Ranch Hand
Posts: 362
  • 0
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic