• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Software documentation management

 
Ranch Hand
Posts: 58
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
author
Posts: 608
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 84
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 ]
 
Ranch Hand
Posts: 362
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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 knew I would regret that burrito. But this tiny ad has never caused regrets:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic