Posts Tagged ‘documentation’
If you want to record what you are doing on your Windows(8?) there is a little program called “Step recorder” that does just this.
With a magical formula it takes snap shots of your screen and saves as a .mht file which can then be opened in a web browser (ie only?).
I use it for instance when manipulating servers and other hairy stuff to record what I was doing. If I need to I can then look for clues why an update didn’t work.
It can also be used for aiding you mom who complains about whatever icon that doesn’t show up when it should. Start Step recorder, let her do her stuff, stop/save Step recorder and then email the resulting file. YMMV
Here is another usage: You have a bug that shows only sometimes. Record what you are doing and wait for the bug to show its face. Look at how you got there in the mht file.
It is, at least in MSSqlserver, possible to annotate fields. Please do.
There are people coming after you to maintain the code base. One day it might be you who come after someone. Start paying it forward.
The field explanation might be in the Documentation but the Documentation is too often faulty, not accessible and almost always not up to date. The database is closer and probably easer to keep in sync with reality.
Don’t think a field name is self explanatory. The field CustomerID in table Customer might be. But the same field in Region is not. Is it the region master or the primary customer or what? By the time the field was created the meaning of this field was clear but not a year afterwards.
The reason I write this is that I presently work in a project where the habile predecessor has written down the meaning of the fields and saved me lots of time and lots more of confidence of what the figures mean and tons of debugging time.
Correction; Considered a warning.
Here is a good rule-of-thumb: If you have to write an SQL with Select Distinct, do adjust your chair, get a cup of coffee, walk around the office but above all talk to someone else because Select Distinct is a symptom of something being wrong, either in the database or in your solution.
/* Select Distinct is normally not needed when your database is lagom normalized. But if you do need a Select Distinct then this is a very good example of a situation that needs to be documented.*/
I found a blog entry at http://www.matshelander.com/wordpress/?p=74 which although lengthy and wordy hits the spot. There is no good notation system for software architecting.
My words: Comparing software architecting to building houses is ridiculous. Just because they share the same name (architecting) doesn’t mean they have a lot in common. Compare a sea horse and a horse and you get the same useless result.
The romans would never be good at mathematics since they lacked a good notation.
What software architecting needs is a good notation. UML is one way but it is not very good for evolving solutions and finding bugs. Code is the best notation I know of but it is too close to the very program and not good at describing architecture.
Besides, after several thousand years of building houses we still miss the estimated cost.
With no information you have one task.
1) deduce the right information
With the wrong information you have to:
1) understand the information
2) find out that the information is wring
3) deduce the new information
I got the coding rules for a big company. 200 pages. I put it to the side with the thought “Noone else has read it either.”
Too little documentation, read or unread, is better than long that is not read.