Write Your Own Documentation

-
Reminder to self: When you are exploring a new concept, or getting familiar with a new technology that you intend to implement,  write your own documentation about it.

By this I mean going beyond "keeping notes", where you say "Tech X allows you to do a,b,c". Instead expand it with how YOU would use Tech X, or how you ARE using it. "We use Tech X at Widgets Unlimited to overcome issues 1,2,3. Standards: We always enable Option A because Option B proved unreliable across a WAN" etc.

This doesn't have to be glamorous. It just has to be personal. Why, and why bother?

  • The act of summarizing everything you've read/seen on a topic helps you synthesize and internalize it. Fuzzy parts become clear.

  • You are forced to really think through the topic, and make it real for your life.

  • You've just created a great documentation resource that will be personally twice as valuable as anything you'll find online or in a book.



It's one thing to be able to lookup how to do, say, Log Shipping in general. It's a completely more powerful thing to have your own specific standard written up about how you do Log Shipping. Your own standard tends to be more concise, and include personal lessons learned. So don't just have a favorite chapter on the topic; have your own mini-chapter.

This is a habit I'm still developing. It's partly a "good internal documentation" habit, but it's also a "how to retain hard-won knowledge" habit. And for me it really started with some great advice in Brad McGehee's "How to Become an Exceptional DBA" book regarding having a "DBA Handbook". I created and maintain such a handbook at our company. We further have created various "Run Books" that walk through how to perform a single complex task. From this I created a document template in Word, and now creating new Run Books is a snap. (This is important: documentation that is easy to create is more likely to get created.)

So Run Books are good, and DBA Handbooks are good. But beyond that, little personal "Technology Summaries" that you collect and improve over time are invaluable.

Do you have a technology on the brain, floating around kinda fuzzy like, with loose references to 2 books and seven blog posts? Write down everything you know about it, add some personal notes, and free your mind.

Comments

  1. UnknownMay 26, 2014 at 1:08 PM

    I like this post, Will. I have had to document my understanding of some new software we're using. I opted against the cold third-person of standard user manuals in favor of first person notes to my future self. E.g., "I considered my options and chose setting B, but you may want to take another look and see if that was the best choice."

    ReplyDelete

Post a Comment

Popular posts from this blog

SQL 2005 SP4 and MSreplication_subscriptions

-
If you're trying to apply SQL 2005 SP4 (or any SQL service pack), and it's failing, and you're seeing error "MSP Error:  29537  SQL Server Setup has encountered the following problem: [Microsoft][SQL Native Client][SQL Server]Invalid object name 'MSreplication_subscriptions'", then you've hit this bug which Microsoft is currently saying they "Won't Fix": https://connect.microsoft.com/SQLServer/feedback/details/521231/failure-during-server-script-upgrade-process-on-database-in-sp-vupgrade-replication-procedure#tabs Probably you've done one of 2 things: You're using synonyms that match the system replication table names You've got some vestige replication tables laying around in one of your old databases My case was the latter. The fix was to find the vestige tables and get rid of them. I found them using the following script: [sourcecode language="sql"] /* This will detect db's containing vestiges of Replication
Read more

Hiding an ASPXGridView Delete button with HTMLRowCreated vs. CommandButtonInitialize

-
It's pretty typical in Administration forms to need to hide buttons on certain rows for various reasons. Particularly it is nice to hide the Delete button if in fact the row in question is being used in other places in the app. This is a nice feature to let the user know up front that the row in question is in use, rather than them trying to delete it and getting a foreign key related error after the fact. For years now in DevExpress ASPxGridView's I have been handling this in the HtmlRowCreated event. And I have been doing it wrong. Before: protected void gridGiftCodes_HtmlRowCreated ( object sender, DevExpress.Web.ASPxGridViewTableRowEventArgs e) { if (e.RowType == GridViewRowType.Data){ int commandColumnIndex = - 1 ; //Find the command column commandColumnIndex = e.Row.Cells.Count- 1 ; //assume it's the last visible colum //Get the command cell for this row GridViewTableCommandCell cell = e.Row.Cells[commandColumnIndex] as Gri
Read more

SQL Server Deadlocks - Easy Quick Start Guide

-
If you find the topic of SQL Server deadlocks a little intimidating and mysterious, you are not alone. But fear not, this Quick Start lays out the practical shortcut I bet is sufficient for most scenarios. Definition: What is a Deadlock A deadlock occurs when 2 threads are competing for similar resources, and Thread 1 HAS A and WANTS B, and Thread 2 HAS B and WANTS A. They’re stuck. SQL Server picks a loser and throws error 1205 "Transaction... has been chosen as the deadlock victim." The BIG PROBLEM if your application has a lot of deadlocks is unpredictable application behavior . This can especially show up in apps that call large stored procs where the failing statement gets rolled back, but the proc itself may just keep on trucking with the next statement. This is all based on what kind of error handling you're doing, whether you have XACT_ABORT on, whether you're doing explicit transactions with BEGIN TRAN or not, etc. Very Probably your application is no
Read more