Can complicated Software systems really be documented?

All managers I worked for at some time or the other asked me to document my Applications. This involved creating UML diagrams, inline documentations and even code review.
UML diagrams are completely useless in my opinion. I submit the following reasons
1. Class diagrams can be reverse engineered. So you can get them when you want them. Can't see how documenting them helps.
2. Sequence diagrams only help as communication tool across major sub systems and no more. Trying to detail them out fails because they get outdated as soon as you start coding. The reason for that being that sequence diagrams cannot be compiled. Efforts to translate them to code fails almost instantly. One argument to create detailed sequence diagram was so that an architect could provide detailed specs to "dumb" programmers offshore. Apart from the fact that this allowed the architects to feel important because they are not drawing sequence diagrams instead of coding I do not know what was accomplished. Besides paying 2-3 so called dumb programmers "$35" an hour minus communication overhead which is obviously more than $0 I fail to see the cost savings.

Enough of ranting though. Having more programmers in the team helps indirectly in long term maintenance. In the above example while the architect could have coded more than just write sequence diagram there is an indirect benefit to the other 2-3 programmers. First of all contrary to popular desire to believe they are not "dumb". Secondly should the architect disappear else where to write more sequence diagrams they will provide enormous security to continue maintaining the code.

Which brings me to the last point. No amount of documentation can compensate for having 2-3 good developers on a project. Thats your only insurance against one of them leaving suddenly. You can document the code as much as you want but the new developers will take as much time to read your documentation as they will to make sense of your source code and if they are anything like me they will prefer the source code as " Source Code is never outdated".

So stop trying to save money by having only 1 guy no matter how smart to develop your system. Should he leave abruptly his documentation wont save you.

Things I would do early on in my next project

1. Install a good version control system in place. Insist that all developers follow a process with respect to it. In my current project we had people (myself included) lock version controlled files from PVCS instead of checking them out resulting in other peoples changes getting overwritten. After as few painful experiences all of us simply stopped doing it. However I would have an explicit rule that no developer can do that from day one.

2. Have a tracker system which is integrated with emails of all users. I have discovered its simply not practical to have people log into the tracker every once in a while to check out if some new issue has been assigned to them.

3. Have categories in the tracker system such as
1. Bug Fixes
2. Queries
3. Enhancement requests

4. Have another category such as UseCase. Thus you should be able to filter all issues by Categories in step 3 and UseCase.

5. Lock down basic deployment issues such as
a. Does the server and client reside in the same network
b. In a client server application can the clients and servers belong in different timezones, different firewalls, etc

6. Have a unit testing process in place. Use JUnit for java or NUnit for java. Insist on building a set of regression testing utilities built from day one. It may be an overkill for some project but I would have one junior developer along with one senior tester to ensure that all unit tests are uptodate and useful for regression testing.

7. Start having a use case test plans ready from as early as possible.

8. Document all environment settings (OS and application variables) from day one and have one person in the team take ownership for maintaining the most current document on this factor.

9. Have an automated build process as early as possible.

10. Have a data migration plan in place. All data migration must be automated. All DDL's must be documented and must be capable of being executed in a automated fashion.

11. Have a utility to perform database comparison to ensure that each build is using a correct version of the database. We modified the Schema Compare Tool For Oracle to allow the deployment team to ensure that when a code is being promoted from one environment to another (Dev to Test To Acc to Prod) we always run the schema compare tool against the current env and target env to ensure that no schema changes are required. Our modified version also compares the Environment Variable Tables between the two versions to check if any environment variables have been added or removed, or if a environment variable has a valid set of values before we perform code promotions.

The above are just some things of the top of my head. But I cannot stress how important data migration and a good suite of regression test cases are. Those two in particular have come back to bite more a lot and I do not intend to treat those two aspects casually if I have a say in any project I do.

Cool description on how to achieve Authentication

My friend Badri described mode of authentication in a cool way on monday

Authentication is based on 3w's
1. What you know ? (Passwords)
2. What you have ? (Smart Cars)
3. Who you are ? (Biometricts)

XML, SOAP , WSDL and UDDI for Web Service Applications

XML provides the Type system, SOAP provides the messaging protocol , WSDL provides the Interface Definition Language and UDDI provides a registry for storing and discovering services.

To invoke any web service the following steps need to be taken
1. Inquire the UDDI registry for location of WSDL.
2. Download the WSDL from the location discovered in step 1.
3. Construct a SOAP message compliant with the WSDL and use the SOAP protocol to invoke the WebService.