Jump to content

Mantra: Documentation, documentation, documentation...


Recommended Posts

My former supervisor beat me over the ears with it... but he was right, I learned the hard way.


Tell me, what is the name of the kids in your class photo? You used to know them so easily so did you jot them down on back? Even your friends of the time? Can you list them today?


Have you ever had a "Blond moment" as the Germans are want to say? You forget someone's name, or how to comment out in PHP or some other moment where you simply do not remember something you did yesterday and will likely tomorrow, just right now it is gone? Memory is a cruel thing.


Document everything! Something will need changing or rewriting down the line. You will be away from a project a long time or someone else will take over. This will happen and it is a pain, believe me.


Case in Point: I was tasked to rewrite a simple read only App used once in a while to look up legacy data, it was called ABE. I planned it , poked at it and built it in Crystal Reports before deciding to do the final in Flex.


I was a good way towards completion when I was told that I had 6 weeks to rewrite a more important App built in Paradox. So I put ABE aside and begin trying to figure out what the new project was all about as I knew nothing of Paradox. Low and behold... ABE is a part of it. Fine, I based the other sections on how I built ABE and used the ABE part in the "Big B" App. Then one day my data is coming up wrong, the sums are different than the old Big B App.


There is NO documentation on the Access version of ABE, but you can get into access to see the SQL statements and what tables are used. But Paradox is a compiled system, so without the original source code or DOCUMENTATION, you have to shoot in the dark and hope your guesses pan out. It took me weeks to finally discover that Paradox had it's own data tables on the network. Now I have 5 oracle data sets and 5 Paradox data sets. Are they the same? So another two weeks trying to compare them to see if they are the same data or a mix or different.


[bare in mind that in the weeks I speak of here I also have days where I am working on emergencies and my weekly Batch Processes.]


Now that I have different data sets that must be queried, I begin trying to find ways to compare the data for duplicates, but each try gives different results. Finally while speaking to the users I discover that the first generation was Paradox, then 2nd generation was Access and a complete instant switch to Oracle, so in fact I have 2 different data sets per application section. So I have to figure out how to port the Paradox data into Oracle, then develop a statement to combine the data of both data sets into one chunk of data.


Now with new data sets I return to my Flex interface to connect the data to the App... and it is written in ancient Sumerian. I do not recognize the code, I documented none of it so I spend another few days trying to figure out what Java classes do what so I can trouble shoot the errors and why my data is not showing, because I did not comment the code or document anything!


Long story short, the deadline was the end of August, all September was finding the Paradox data and sorting it and October has been porting it to Oracle and developing SQL statements etc and we are ending October and I am not finished.


Imagine if I had had documentation that described what Big B was and how and who used it. What if the Paradox and access versions of ABE were documented and the Paradox version told me where it gets it's data. What if it explained that in 3 of the 5 sections making up Big B, I would have Oracle and Paradox tables to deal with. What if I had just commented my Java classes, Action Script classes and my main interface to remind myself what does what and why. Just guess how much quicker it all would have gone?


Documentation, Documentation, documentation! Write and keep notes. Jot down any connections with databases that the web site uses. Comment even the most mundane code as it may not be so clear two months from now. Use clear names that describe what something does or is. Comment you code some more. Finally when you are finished document the process you used, any info on old databases or such. Describe issues you had and who you fixed them (this may be nice one day when you have the same errors in another project) and describe in this final documentation what it does, who uses it, what technologies are used... anything that may help you or someone else later fixing or re-writing it.


It all may be clear today... but not two months from now. Even trouble shooting is easier when you have comments denoting the beginning and end of sections you may want to find fast when scrolling.


I suspect most of you will say that is a good idea and then not due it like me. I also am sure that one day you will have a bad time of it and wish you had and start doing it then... after you are bald or gray. Trust me, make the effort.


Thanks to Quyen who's comments in my 2 mistakes of CSS thread seeded the idea for a thread on this subject.

  • Like 1
Link to comment
Share on other sites

  • 12 years later...

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...