January 7, 2009 at 8:24 am
I see most everyone saying the documentation from the code point of view is critical. And that does make some sense, make notes in the code as you go.
However the system is different. Outside of the compiled code, the servers you've deployed on, the networking, the connection strings, service accounts, etc. This stuff is hard to document and more importantly, hard to keep track of. It's just difficult, and things change often. They shouldn't, but I've seen this time and time again that changes are made and it is hard to keep up with documentation.
Management asks for documentation, but they don't read it. They just want to see something. If they ask for lots of detail, then you can always do it, but I've explained that I can spent hours on this and it will likely be out of date and not well maintained.
I just don't think there's a good way to do this. I've seen the nuclear industry try, and they kill more trees than you can imagine trying to file paperwork and things still get out of date there. I'd still argue that enough of a document to let another person of a similar level of skill and experience is what you need.
January 7, 2009 at 8:38 am
I would agree with the changing configurations. The documentation though that is useful is that which would guide someone to be able to reconfigure the application. Something that states what communication protocols\ports are used, what permissions are required for each component, what settings need to be changed when rebuilding a system on new equipment etc. This is something that a Developer would know or QA may know from the developer but your educational services folks that right the end user documentation would not care about.
January 7, 2009 at 9:02 am
I disagree on it "being difficult" to document deployed configurations and keep track of operational details. The number one problem that we see in the field with customers is a low level (or no level) of operational maturity. It doesn't matter to me if you follow MOF or ITIL or some homebrew change management process... but if you're not documenting for posterity what you're GOING to change before you change it, you're going to have trouble someday that could've been avoided. But operational documentation wasn't where this conversation started out.
On the ROI question: every study and book that I've ever read had it at 80x or higher cost for late-breaking changes to software projects compared with changes made in phases earlier than maintenance (i.e. already in production). I've been studying the video game industry of late and the industry average seems to be about 60% of the total cost of any given AAA title is REWORK that could've been avoided by better specification earlier in the process.
Documentation is like unit tests. If you don't write down what you're going to do BEFORE you try to do it, how will you know when you're done? Or if you've even done the right thing? Or all of the things that needed to be done? The most common problem of documentation and testing that I've seen is that companies try to separate the duties, but unfortunately, only the developer has all the requisite knowledge to do proper code-level documentation and unit testing: it can't be farmed out to another brain who didn't write the code.
January 7, 2009 at 9:13 am
As for system changes there are tools out like MOM for Windows that can do this. Not sure how deep it goes as I never had to configure this.
While MOM is often used to find problems it is capable of tracing system changes too (for example service packs). The question is more of how to capture this adequately and in a form that someone else but the network "nerd" (speak engineer) can read with some level of confidence.
As for SQL server changes there are excellent tools (for example SQL DOC) that can just about extract the state of the master databases. This does not extract everything of the SQL server configuration - this should be doable through MOM.
Maybe I am just too naive to think that there is an easy way.
January 7, 2009 at 9:33 am
Not naive at all. Just too few people do it.
SCOM (which MOM was rolled into) is designed to manage operations, applications, automate routine admin tasks, etc. It's a bit bigger than just a configuration management database.
http://www.microsoft.com/systemcenter/operationsmanager/en/us/default.aspx
There are management packs available for most Microsoft apps and a lot of 3rd-party apps. It's also possible for developers to expose important events and tracing information themselves, or (worse case) for the admins who have to live with the devs code to write event log watchers, file watchers and such to keep an eye on the health of the system.
January 7, 2009 at 9:53 am
Steve Jones - Editor (1/7/2009)
I see most everyone saying the documentation from the code point of view is critical. And that does make some sense, make notes in the code as you go.However the system is different. Outside of the compiled code, the servers you've deployed on, the networking, the connection strings, service accounts, etc. This stuff is hard to document and more importantly, hard to keep track of. It's just difficult, and things change often. They shouldn't, but I've seen this time and time again that changes are made and it is hard to keep up with documentation.
Management asks for documentation, but they don't read it. They just want to see something. If they ask for lots of detail, then you can always do it, but I've explained that I can spent hours on this and it will likely be out of date and not well maintained.
I just don't think there's a good way to do this. I've seen the nuclear industry try, and they kill more trees than you can imagine trying to file paperwork and things still get out of date there. I'd still argue that enough of a document to let another person of a similar level of skill and experience is what you need.
I agree that many times management asks for documentation and never looks at it. That is one of the most frustrating things about having to do system documentation.
Yes, it can get out of date, but I have found that even out of date documentation can be helpful because there are usually key bits and pieces that have not changed and help you understand the whole.
Jack Corbett
Consultant - Straight Path Solutions
Check out these links on how to get faster and more accurate answers:
Forum Etiquette: How to post data/code on a forum to get the best help
Need an Answer? Actually, No ... You Need a Question
January 7, 2009 at 9:54 am
Steve Jones - Editor (1/7/2009)
I just don't think there's a good way to do this. I've seen the nuclear industry try, and they kill more trees than you can imagine trying to file paperwork and things still get out of date there. I'd still argue that enough of a document to let another person of a similar level of skill and experience is what you need.
Depending on the size of your organization, the likely reason you may feel the way you do is because it really isn't in your role to manage this kind of system documentation. Change Management is difficult, and is very often the responsibility of a specific person or a group of people. At the very least, it is not something to tackle as part of a specific project, staring at a blank document late at night and hours before releasing new code.
Plenty of industries have tried and failed at this task simply because they try to treat EVERYTHING as important. Like the nuclear industry, I've seen health care become so overwhelmed with information and documentation that the important stuff gets lost.
January 7, 2009 at 10:44 am
It sounds like what Michael is saying (in part) is "prioritize your documentation". In other words, determine what the important things are to document, and focus your efforts there.
I think most developers and DBAs don't have any formal training in how to document - I know my interest in it was the result of one teacher in college who insisted on it in my COBOL I class (dating myself, I know!) 😎 I took COBOL II from her as well, and when she made us go back to a program from the first class, I realized how helpful those comments were that everyone else had complained about and skimped on. I had my program modified and running in half the time it took the rest of them, simply because my code comments were verbose enough to contain almost everything I needed to determine the best way to make the changes. I've been a proponent of documentation ever since.
I've written user docs, system (application) docs, occasional white papers, specs for internal and external developers, etc. over the years, and never regretted a single line of it. In this day and age, it's not necessary to kill so many trees, since most documents can be kept online, where they're much more easily accessible. And with wikis and intranets, finding them again is becoming easier as well. 😛 For disaster recovery, you'd want a separate off-system copy, but that could be in the form of a CD/DVD as well, to be kept with the "recovery package".
And I have to agree with Jack about out-of-date docs being better than none. But if documentation was seriously considered as an essential part of any project, that shouldn't be an issue. It's not the fault of the documentation; it's the fault of whomever is putting the obstacle in place to having updated documentation, whether that's the developers or the management. Documentation is a tool - use it wisely.
Steph Brown
January 7, 2009 at 12:22 pm
In the past 10 days I have been bitten by the "no documentation" ghoul.
If you have too much you can prune it, if you have too little then what do you do?
Today's situation was someone ringing me up to ask if I had permissions to carry out a task.
Yes I had but they weren't able to articulate what that task was.
It turned out that there was a windows app to do what they wanted but the app has tight control on who can do what. It doesn't have an intuitive user interface.
My first question was "where is the help text"?
It got descoped from the project
Where are the instructions for using the app?
There aren't any
Are there any setup instructions for the app to tell you what permissions to set?
No.
The app is one that isn't used very often but when it is needed it is essential. Not being able to use it will cost a 5 figure sum.
I dare say descoping documentation in any way shape or form saved 5 days worth of effort say 15% of the project budget. Probably sounded a lot at the time.
I've had another situation where someone needed change data in a database. The inter-relationships between the various things they needed to do was very complex so doing it manually was a daunting task.
Fortunately there was a tool to do the job
Unfortunately the only person who knew how to use it had left and no-one else knew where the install software was or how to use the tool.
OK so you script up the data changes and get the job done. Or have you? The inter-relationships are complex and undocumented so you may have missed one or more and that would be enough to nuke whatever depends on that data.
We have jobs that monitor our servers and one of them went wrong on 1st Jan. We could see the data getting written into the DB but God only knows where it was coming from. We knew it was an SSIS package but imagine trawling through 200 servers trying to find out which one contains the crucial job?
I stick with the "write like you never want to have to support it" school of thought to avoid precisely the examples shown above.
January 8, 2009 at 9:27 am
How long did it take you to figure it out, David? If it's not long, and you document it so this isn't repeated, perhaps it is worth going without documentation.
It's hard to know when it's worth it. I'd argue that lots of documentation never gets reused. Or it's lost, so is there value in spending too much time on it?
you should do some, put it in a central place, and at least there's something. I just question the value of extensive documentation.
January 8, 2009 at 10:22 am
Steve Jones - Editor (1/8/2009)
I just question the value of extensive documentation.
I understand the quandry you express by documents that seem to burn a lot of front end time, and never get updated.
I like the camp of thought that treats documentation like a "living" document, something that is updated every time you touch something. It does not have to be complete up front, and is never complete until the product is dead and buried in the tombs of legacy.
For example, in aviation, especially military aviation, they update the manuals constantly as needs become known. I treat my documentation with the same tenor. Granted, application and system documentation won't likely cost lives, but it could cost many a livelihood, making decent products die long before they should.
This is why, in my opinioin, an internal WIKI is such a great tool. It is founded on the principle of a "living" document. It offers the ability to allow merciless changes, and track them all. It enables links, cross-links, and hyperlinks without having to be a web publication genius. It indexes and categorizes. It is in my opinion one of the greatest inventions on the front of documentation to ever have seen the light of day. It takes the pain out of it.
However, as with any form of documentation, it dies when it is forgotten and left to rot. It also becomes unbearable if it gets into too much extreme detail, bording on a replica of the system it documents. Docs are meant to point you in the right direction, and give understanding to the processes and methods... but not necessarily a robotic instruction list (with some exceptions, like DR procedures).
You don't have to do all your docs up front. Rough the structure, purpose, and initial major components. As you build parts, add more and more detail. If all who follow that project or system treat the documentation as part of the system, rather than a one time dead write-up, you would see the order and stability it adds to the system as a whole.
The real problem you seem to be making example of is, "None (or few) do it right, so why do it at all. I have to figure it all out anyway. Therefore skills are better than docs."
To this I would say, don't compare apples with potatoes. One is root and the other is fruit, but both are good for the system.
January 8, 2009 at 12:24 pm
It was never really a big deal when I started working in the company I am now. My boss always asked me whenever I got stuck (in my learning phase): "Where did you write your plan down before you started!" and if I did not I was in trouble. Those "documents" were never kept though. They were just for you to plan your work. This brings me to my next point. Ever heard the saying: "Plan your work and work your plan"?
Back to documentation, I think it is important although like Steve says, normally a developer shirks at doing that because that time could be well used for development. Funny that I just read this post tonight about documentation on TechRebublic. In favour of documenting your work I have to say that it's happened to me that I had to fix some code someone else wrote and first had to figure out what this person meant to do before I could fix it. I think I will definitely start documenting my work this year.
:-PManie Verster
Developer
Johannesburg
South Africa
I can do all things through Christ who strengthens me. - Holy Bible
I am a man of fixed and unbending principles, the first of which is to be flexible at all times. - Everett Mckinley Dirkson (Well, I am trying. - Manie Verster)
January 8, 2009 at 1:53 pm
Manie Verster (1/8/2009)
... I just read this post tonight about documentation on TechRebublic...
URL didn't seem to work for me.
January 8, 2009 at 2:25 pm
January 8, 2009 at 3:09 pm
Timothy (1/8/2009)
http://techrepublic.com.com/5208-12845-0.html?forumID=102&threadID=281804&messageID=2673975
Thank you, that one works. Kind of a "duh" moment when I realized the extra "http" on the front of the first link. Not much to the article though. Just a short about putting the change number in the code comment.
Viewing 15 posts - 46 through 60 (of 89 total)
You must be logged in to reply to this topic. Login to reply