Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 

A Dearth of Comments

By Steve Jones,

I was having lunch with a friend the other day and he talked about how much documentation he has to complete for a project and he was lamenting on how much he hates writing documentation. But he's a fairly meticulous person and couldn't short-change the job and write less than he feels is necessary, which in this case would be a detailed enough description for a semi-technical person such as myself to recreate the system.

My thought was this was overkill and we argued a bit about it. I write  a lot, and I always tried to ensure there was documentation with a project, but not detailed documentation. My thought was that I would want ensure that someone close to my level could understand what I had done, or more likely that I could remind myself what was in place, but that I wasn't writing for a junior developer or administrator to understand things.

When I learned about programming in high school and college, I hated documentation. We had to write what I consider silly documentation in our code that explained what was happening in each module, probably just to show the professor that we understood it. There were even times when we had to write the documentation first, outlining each section of code with documentation and the filling in the code underneath, essentially duplicating our work.

My viewpoint now is that I want to comment enough so that someone of close to my skill level can understand what I've done. I know that most of this documentation will get used in two situations, a disaster, or I've moved on. In the first case, you'll make do and just get things running, likely not digging in too deep to the documentation. In the second case, someone of close to my skill level will be needed to keep things running.

In either case, it's highly likely that something will have changed in between the time I've written the documentation and the time that it's needed. I'd argue that poor documentation can be worse than no documentation, or sparse documentation, and I'd prefer having some rough outlines to guide someone, not teach them.

To me, documentation is just a guide to the system. It still takes a human, with some level of required skill and experience, to make it work.

Steve Jones


The Voice of the DBA Podcasts

Everyday Jones

The podcast feeds are now available at sqlservercentral.mevio.com to get better bandwidth and maybe a little more exposure :). Comments are definitely appreciated and wanted, and you can get feeds from there.

Overall RSS Feed: or now on iTunes!

Today's podcast features music by Everyday Jones. No relation, but I stumbled on to them and really like the music. Support this great duo at www.everydayjones.com.

I really appreciate and value feedback on the podcasts. Let us know what you like, don't like, or even send in ideas for the show. If you'd like to comment, post something here. The boss will be sure to read it.

Total article views: 319 | Views in the last 30 days: 1
 
Related Articles
BLOG

Who writes your documentation?

I’ve been thinking recently about who writes the best documentation. Not including a professional te...

BLOG

Podcasting

I'm working on getting a small studio set up for some podcasting of the editorials. That means I put...

FORUM

High level design documentation required for SSIS

High level design documentation required for SSIS

ARTICLE

Podcast Announcements

Podcast Feeds

BLOG

Podcasting

A new video setup is on the way!!!! Actually I'll do a couple podcasts on podcasting over the hol...

Tags
documentation    
editorial    
 
Contribute

Join the most active online SQL Server Community

SQL knowledge, delivered daily, free:

Email address:  

You make SSC a better place

As a member of SQLServerCentral, you get free access to loads of fresh content: thousands of articles and SQL scripts, a library of free eBooks, a weekly database news roundup, a great Q & A platform… And it’s our huge, buzzing community of SQL Server Professionals that makes it such a success.

Join us!

Steve Jones
Editor, SQLServerCentral.com

Already a member? Jump in:

Email address:   Password:   Remember me: Forgotten your password?
Steve Jones