cancel
Showing results for 
Search instead for 
Did you mean: 

Documentation: Your Future Best Friend

Level 9

I have a confession: I like documentation.

I know.

But I have good reasons. Well; some reasons are better than others. I like to type (not really a good reason); I like to write (although I'd argue I'm not all that great at it); and I like to have good references for projects I've done that will hopefully be useful to any future person--or myself--who has to support what I've put together (OK, this is actually a good one).

When talking about data projects or DBA-related work, reference documentation can contain a lot of nitty-gritty information. There are two specific areas that I think are most important, however. The first of these is useful in the case of Business Intelligence projects, and usually takes the form of a combination Data Dictionary/Source-to-Target Mapping listing. The other is in the vein of my post from last week wherein I discussed asking the question of "why" during the early stages of a project. Even having only these "why" question and answers written down can and will go a long way towards painting the picture of a project for the future person needing to support our masterpieces.

As good as it truly is for all people involved in a project, writing reference documentation is something that isn't necessarily easy or a lot of fun to do. One of the most frustrating things about it is that in a lot of instances, time to write this documentation isn't included in the cost or schedule of the project; especially, in my experience, if it's following something like the Scrum methodology. In the case of a "day job", spending time on documentation may not have the same immediate need, as the people who participated on the project theoretically aren't going anywhere. Furthermore, people spending that time takes time away from other work they could be doing. In the case of an outside consultancy, paying an outside firm to sit around and write documentation has an obvious effect on the project's bottom line.

If I had to guess, I'd say most of you readers out there aren't as into documentation as much as I am…I really do understand. But at the same time, what do you do for the future? Do you rely on comments in code or something like Extended Properties on database objects?

And, for those of you that do attempt to provide documentation… do you have to make special efforts to allow the time to create it? Any secrets to winning that argument? ;-)

16 Comments
Jfrazier
Level 18

One of my mantra's is "Thou Shalt Document"...this included comments in code.

It must be 3 AM friendly.  It sucks being woken up at 3 AM and dig through code to find out the programmer is of the mindset that the code is self documenting.

In a prior life when we set up the original automated operations team we set up and specified coding requirements....this included indention, block comments, no nested function calls, etc.  The purpose was to make the code as well documented and 3 AM friendly as possible. 

Yes I agree most projects do not include time for documentation.  My solution although I am bad at it is to document as I build...document each module and assemble at the end into the final document..even without final edits it should provide a working view of the project...

My favorite phrase regarding lack of documentation..."this page intentionally left blank".

Bronx
Level 15

First, you may wanna check out this article I wrote a while back: Technical Writers - The Unsung Heroes

Now to answer your question about how to get the writing outta the way in an accurate and efficient manner. The secret? Cheat. In other words, delegate. Have a network of SMEs and email them your questions, needs, etc. More often then not, they're happy to help.

mcam
Level 14

its funny how so many techies do a really bad job of this and pretend its not needed.

I am a convert though - it has saved me too many times

cahunt
Level 17

Jfrazier‌ that's how it all started. Write your lines of code and document, notate, make notes of what each line or section does, label a Function with the details of where it applies and what it calculates.

Once you cross a few hundred if not few thousand lines of code your lack of documentation will drive you nuts! If it is not documented, how do you know. Granted, you could "know" but when it comes to making changes, redesigning - you almost need to re verify due to your lack of documentation, or hard Proof that is it the way you think or say it is.

I like to document as you go, or at the very least for visual teaching purposes - take screen shots that will be used to build the associated SOP for this process or procedure.

Coding, Configuring - Document as you do, build it into the script so that the proper descriptions are in place and do not have to be verified and added after that fact.

If not for the sole fact that you or someone else will look at it later, document like crazy! Document it now, so you do not have to re learn or figure it out all over again a few months down the line.

It's like taking notes in that sloppy hand writing that takes you 5 minutes just to figure out 1 sentence. Basically Useless, but then again it's the lack of documentation. Therefore Documentation is always Useful (when accurate).

Jfrazier
Level 18

We also had a "modifications section" in the code to list changes, date, ticket number, and person doing the modification.

Further details were included at the point of the modification.

cahunt
Level 17

As long as these are updated at they should be - all guess work is removed - even when needing to go back to whomever made the last modification.

Nice inclusion!

Jfrazier
Level 18

We also had code review...it was the reviewers responsibility it adhered to all the coding standards...including comments/documentation in the code.

It worked really well.

cahunt
Level 17

That is a grand idea.. something we are trying to bring back - Code review, Peer review - just give me some extra eyes on this before implementation to confirm the designer/engineer didn't miss anything or mistype anything.

  When no one is speaking up, or even asking - Why is that the way it is - the process becomes useless. This is a true give and take. Providing no feedback means you don't get fed, and Ignorant Minds go Hungry and Homeless!

Jfrazier
Level 18

I like peer review..but it does have overhead.

I know for a fact it reduces issues during implementation...but the overhead factor in a busy shop can slow productivity.

airbornegeek
Level 9

"3 AM Friendly"... Love that. Stealing it :-D

That brings up a good point--I try to explain some stuff in-line in ETL processes and stuff like that, but I tend to pour more effort into [a] larger, more over-arching all-encompassing document(s). Although that's good for giving pieces of it to non-technical users or running things by the BA for confirmation of logic/rules or having to pass on to someone else in the future for further development work, that's not 3 AM-friendly at all, because ain't nobody got time for that at 3 AM.

airbornegeek
Level 9

Will definitely check that out, thanks!

Delegating is great...Still need the time to get pieces assembled and into a coherent piece (if doing a big doc to cover a whole solution), but like Jfrazier‌ mentioned, even just tossing all of these pieces into a doc as-is can be a big help.

airbornegeek
Level 9

Excellent--I've had templates before that included this, too. Listing where it came from, who dunnit, quick explanation of the change and where in the doc it is. Great thing to include.

tigger2
Level 13

Q: Do you rely on comments in code or something like Extended Properties on database objects?

A: Only when I expect someone to find their way into the code (like me) and it's a little creative or I copy-paste something I didn't read or fully understand.  I always copy the URL of the site(s) I pulled the original code from and put it in the docs right where it's used or, if it's something I fumbled through I put the link to the API docs (or similar) that I read from. Other than that, when coding, it ranges from putting in some comments here an there and documenting command line options to possibly needing to format all comments in functions/methods/classes to a standard so they can be used to auto-generate API documentation, which always feels like an amazing accomplishment.

Q: And, for those of you that do attempt to provide documentation… do you have to make special efforts to allow the time to create it?

A: Special effort (for me) is only when taking into consideration people who never perform the work on a daily basis and need procedures. Screenshots are created, little workflows and small descriptions of "why" are needed.

I also try to spend a little time carving out a "private shared place" for admins to put shared docs in (can be sloppy-er), and a "public shared place" for others that just need process diagrams or lists or non-admin docs.  This is usually a folder/sharepoint area with restricted permissions for admins, then a small set of documents, wiki, or sharepoint site for everyone else.

Also: If there is a "gotcha" I highlight that part in red *before* the person executes the procedure and right before they actually execute the thing that can cause the gotcha/issue. similar to this:

Note: This procedure will reboot all app processes and disconnect all users.  Outage normally is about 10 minutes.

do something x

do something y

Note: This is the command that disconnects everyone.

do something z

Q: Any secrets to winning that argument? ;-)

A: Nope.  All my "for users/maangement" documentation hopes and dreams eventually turn into outdated jumbles because nobody updates the documentation, or all updates were communicated via IM or email and everyone stashed them away in their personal documentation area (usually email or their brain).  I also secretly believe that "documentation" is just a standard check mark on some "things we need to do" plans so as soon as you say "yes" to it the box is checked and no one ever looks at it, or planned to look at it.  When someone finally looks at it they see it's >= 6 months old and question it (thankfully) so they don't follow it. Then I have to update it .


jkump
Level 15

Personally, I am huge fan of documentation.  I have been known to spend the first weeks of a project or job reviewing and/or rewriting visio diagrams for each of the projects I am assigned to.  Then, I spend time with other teams documenting as well.  I have also mentored many helpdesk and entry level techs on the importance of documentation and to make sure that they are updating the existing documentation and/or creating documentation.  Even simple word documents are better than tribal knowledge.  That is the greatest battle in every company that I have worked with is the removal of tribal knowledge.

Keep up these posts as I enjoy the intellectual curiosity!

datachick
Level 12

The best documentation is just "writing stuff down" so that you can see it right where you need it. In the code, in a model.  My writing stuff down happens right in the data and UML models.  It's just part of the modeling effort as far as I'm concerned.

Jfrazier
Level 18

On the topic of just writing stuff down....

There is the "official" documentation and then there are the personal notes.

The personal notes I keep are in a simple text file because it can be read from pretty much any environment.

It lists common "situation" and what to do and contains commands, results, etc.

It then has the less common situations or issues and how to resolve them as they have been encountered over time.

In many ways it is more of a cheat sheet, but it gets you through 80% or more of many situations.

It grows as new situations are encountered.  It evolves as products change...old resolutions are retained in a block with product versions supported in case you go to a shop using an older version.

A former co-worker didn't believe in documentation.  His name was Cliff.  His documentation has since that time been termed "Cliff Notes - This documentation intentionally left blank".

About the Author
Kerry Tyler started his SQL Server career when he debuted as an accidental DBA in 2005. It wasn't all bad, as he had been hoping for such an opportunity. Seeing Reporting Services 2005 demoed for the first time sealed the deal, and it has been all data ever since, leaving the worlds of networking and systems admin behind. After being a full-time dev/operational DBA with everything since SQL 2000, Kerry is now back to BI, as a Senior BI Engineer/Consultant in Nashville, Tennessee.