Monday, March 27, 2006

Does Documentation Methodology Exist?

This is something I have been thinking about for the last 2-3 years, I see situation where companies have created a lot of wonderful applications.

However there is no documentation as to what those applications are, what code, databases, tables, servers.

I know this is a part of the argument about coldfusion developers not being computer scientists, and perhap's we're not..

But how come there isn't some research or tools on this?

Am i the only one concerned with the overwhelming lack of documentation methodologies?

I mean, currently i am on contract, and we don't have documentation of our applications, and we want to create that, but don't have a clear method as how to extract that information and put it into an updatable and digestable format.

There's no list of applications, there's no manual or bibliography of coding style's etc. They have good people here, but how can we put it together...

I mean we like many people, don't have the time and energy to browse by hand every aspect of the sites, and then also browse thru the code, databases, structures etc.

There must be a means, to extract that information and present it in a digestable format.

Have any of you seen tools like this?

Does a documentation metholodgy exist?

Or does all that matter is that we put comments in our code?

This just personaly irritates me, because we all want to get to this higher level of professionalism, as an industry, but do we cover all the bases that includes?

Just a question.


  1. We have Fusedocs and CFCs have self-introspection which is the best kind of documentation: auto-generated.

  2. That documents your code, but does it document what servers, databases, tables, columns...

    And that's a bare minimal to be honest. That just grabs content from the files, doesn't indicate which ones pulled together equal to an application..

    I am not saying it's bad, but it's not a complete documentation methodology.

    Not that i have seen or heard of anything better...

  3. I think there is quite a bit of guidance on managing a software development project. The first two that come to mind are RUP and CMMI.

    Both of these are about managing the entirety of the development process, including all sorts of documentation and can be a bit abstract. Neither of them really address tools (other than the RUP pushing other Rational tools that cost a fortune).

    You'll also find lots of enterprise tools that claim to tackle the documentation problem, but I think you're probably better off just using document templates in word processors and spreadsheets until you find a tool you use during your develpment process that can lend a hand in the documentation area.

    I use Enterprise Architect for a lot of my design work, and it has a pretty robust rtf editor, but it certainly doesn't take care of the whole job.

    So much of what we normally think of as documentation is really process management. A document without context usually just gathers dust.

    A good UML tool will at least let you do your drawings easily. Some can even do things like inspect databases and file systems to help you document your system.

  4. I see documentation and planning as two different things. For planning I've used Adalon and gModeler in the past. You need a wiki too. I agree, there should be better tools that do introspection and allow developers to document (even make changes to) relationship and databases. I think a lot of developers design these tools and the UIs are just painful.