What Documentation?


I’m crazy about documentation. More than that, I’d call my self a “Documentation Guy”. Not only do I go through extra steps to document all technical and process decisions for the systems I control but I also hound the people on my team for documentation that in a round-a-bout way impacts my space. Why am I like this? A couple of reasons, some are selfish and others are not. Let me explain.


Good documentation is a crucial piece of a solid IT organization. I didn’t always believe this and would be the guy saying “Who’s going to read that?” Problem is I would move onto another project and bam, something would happen and screw up a configuration I made in the past. No one knew what I did and usually there wouldn’t be time to figure things out because of these critical business applications needing to be online. This brings me to my first point:


Point #1 – Good documentation allows those that will be maintaining your systems later on to know what you did to set them up


This is probably the biggest impact that good documentation can have on you. Wouldn’t it be terrible if you are now part of the Domain Administrators group and while on vacation you get called because SMS is down and no one knows how you set something up? Of course documentation, and more specifically detailed documentation, also gives back to the company and others knowledge that you have acquired through training and experience on the job. For any organization to progress and move forward they need to minimize the learning curve that new team members have. If processes, procedures, and technology implementations have to all be relearned whenever a new person joins a group then they will have to work just as long or longer to get to the point you are at. Which means that:


Point #2 – Good documentation helps an organization progress long after you have left


This point is largely about the long term benefit you are giving to the company however it also has a certain level of satisfaction to it. Personally I want to know that the work I did for a company was not all for nothing and lost after I left. The best thing that I can do for my legacy to be carried out is to document the thoughts and ideas that went into building infrastructures along with the technology because this ensures not only that things are done right but that the people doing them know why they are.


Point #3 – A sysadmins memory is usually lousy


We all need to reference not only what we did but also what others did later on in life when making changes or implementing either a new technology and/or process. How can we do this without documentation? Anymore its becoming a rarity when all you do is one job. Because of this everyone forgets something they did in the past especially when it comes to technical configurations. Document it well and you’ll save yourself headaches in the future.


Point #4 – You have to know what you are talking about to make good documentation


I’ve met a lot of really smart people over the years and hands down the one quality that the people I’d refer to as “guru’s” have in common is good documentation skills. They have to know what they are talking about in order to put technical thoughts down on paper. Documenting things almost always leads to a deeper understanding of a product or technology. Take your SMS infrastructure for example: If you are documenting how your site will have NLB configured as your Management Points you’ll start asking questions about how the process flow works and answer them before anyone else does. How does NLB disperse traffic between the Virtual IP and the different hosts participating? How do clients know how to go to that Virtual IP in the first place? What happens when one of the hosts goes down? Once you start asking these questions and doing the research to answer them you will be able to speak with authority on a multitude of subjects.


Point #5 – Complex systems need to often be set up in a repeatable manner


When your dealing with something as complex as Domain Administration or a Systems Management product many times you will be asked by management to roll out a new environment in a very short timetable. The thought here is you’ve set this up once already so its cake to bang out a new environment right? When doing something like this there are often dozens if not hundreds of steps involved and the fastest way to accomplish them is to follow appropriate steps in the correct order. Good documentation here will save you trial and error time by not rooting around for product or system requirements as well as other dependencies you accounted for in the past but don’t have the time or resources now to research. A perfect example of this are server builds. Even if you have an imaging process in place there are often post setup tasks that must be done to ensure that systems are configured on the network properly. How about all the IIS configuration for SMS 2003? Instead of figuring out later on why you are having some DP issues with BITS, follow your documentation on how to set this up correctly in the beginning and save yourself the headaches down the road!


 


How should people get started with documentation? I actually don’t think its always the best to start documenting policies and high-level architecture if you don’t have much experience with documentation in the first place because chances are the results will be weak. Do you help out your desktop guys a lot with troubleshooting a specific application or network problem? Try documenting what your process is to resolve it. Go DEEP into detail! Call out explicitly in your documentation who your intended audience is and give an overview of what your documentation is trying to accomplish. Always include the ability to update it later with versioning, author(s), and track changes clearly listed for others to reference in the future (please, no jokes about documentation inside of documentation). List out your steps and remember that the people following them will most likely be technicians and not Engineers or Sysads. Fear not screenshots – they are your friends! Don’t skimp out on the good stuff either such as Conclusions and where to go for help if the documentation doesn’t prove effective for everyone. And if possible always include references or links to more information to those interested.


 

33 thoughts on “What Documentation?

  1. My organization is serious about documentation. They are also serious about process. Per process we schedule meetings with our peers to review our documentation for a new scripts, programs, packages, procedures, etc. I think documentation is essential not only to effectively reproduce our efforts but documentation also provides a degree of insurance in an era of high personnel turnover. What bothers me is the process of documentation is overly burdensome. Our documentation templates have 50 fonts, bold, italics, underlined, tables, graphs, etc. I think I could effectively document my processes simply using notepad. We generally spend an hour on a document review. It turns out being an hour of "You used the wrong font here" or "All click actions should be highlighted". It seems almost no one can see past the process to try and understand what is being documented. Or documentation templates are too inflexible to deal with the many issues that we encounter and I frequently deviate from the template while attempting to document something that the template doesn’t allow for. In summary; documentation good, process bad.

  2. Excellent stuff, all…

    I am to this day very grateful for my military technical training because it exposed me to "tech manuals"… we lived (and died) by them when at sea… there was NO one to call!! It was you, and "the book"!. Subsequent work after that in the defense industry required me to do a lot of original work, but once again, using "gov’t std" format and so on… this all became second nature, such that today I can whip out a decent doc very quickly… WORD is your FRIEND!! To the point earlier about critique of form over substance – RIGHT ON! Focus on what it says; not how it looks!

    OTOH, once you have aq decent template set up in word, and you learn how to use tags for section formatting and so on, it is a breeze…

    Lastly, let;’s not forget one of the most IMPORTANT documents of all, and one RARELY used IMHO:

    The CHANGE LOG!

    I try and keep ALL my SMS actions in a simple and easily accessible Excel worksheet wherein I create a new row for each action taken on my site servers… this is only for substantive changes, not the minutae… but it has saved my butt on more than one occasion, especially when I needed to go back MONTHS to recall something I did, or an odd password used (and long since forgotten perhaps)…

  3. Amen! Of course, as a tech writer, I’m part of the choir. But I’ve been behind the terminal, too. It’s always interesting when you walk in as a contractor – you never know if you’ll find a well-documented network or a mystery that could boggle Sherlock Holmes. Usually it’s the latter. My favorite SMS-related story: we had just installed SMS 2.0. We ran network discovery and then printed the topology map showing the routers. The next morning when we came in, SMS wasn’t working. We traced it to problems with the IP network. Turns out the routers guys had done some major reconfiguration and by about 10 AM they didn’t know which end was up. We gleefully offered them our topology map so they could put it back to something that worked. 🙂

    Great article, Richard! Keep ’em coming!!!

    So, on a related note, one thing we’ve been kicking around in the doc world here is, how can we give you guys a better base for creating your own documentation? With the SMS Scenarios and Procedures we’re trying to give you more planning worksheets, figuring good planning docs turn into good configuration documentation. Is that helping? We’re also experimenting with putting all of the procedural stuff in one place, like in the Security book we put it all in Appendix E. Does that make it easier to cut and paste into your own docs? What else could our team do to help you doc your SMS operations? We always welcome your feedback at smsdocs @ Microsoft.com.

    Cathy Moya | Technical Writer, SMS & MOM | Enterprise Management Content Group | Microsoft

  4. Cathy, I’m a keen advocate of the KISS model. Keeping as much related material in a single logical location (an appendix as you suggest)… having readily usable "templates" for example as you suggest – for easy cut/paste int our own doc(s) is terrific. Ont process I use here at CVS: I have an "empty" shell of several types of docs… for example a Project Plan, Test Plan, Requirements Definition doc, etc… these are already formatted with a standard cover page (with logo graphics and water marks), header/footer, TOC and List of Figures tables, and several empty "chapters" of text – usually with three levels of headings… this makes it incredibly easy to create a new doc of whatever type, and simply build it from this pre-existing shell… like a pre-fab home! This gives all my docs a common look/feel, and saves me having to try and remember "how did I do that the last time???" I’ve even followed this paradigm by copying the Microsoft look/feel of "white papers" for docs more suitable for that style of writing…

    So anything that you experts in the documantation field can do to simplify the documentation process, especially in a way that is easily duplicatable by just about anyone (regardless of their comfort level with advanced WORD features) is a huge plus.

  5. How about posting some of your most successfull templates or document shells for all of us document challenged people? It will help get us all started and will be greatly appreciated

  6. 2centz

    Documentation has its place and I agree documenting can be helpful when trying to understand a process or history of a given system or procedure. When you have a critical system down in a production environment that is costing you money or face time with the VP on why the system was down, searching for the for the correct documentation on your present predicament is a waste of (Valuable) time!

    I document when ever possible and post to my team 4r review n such. But my Nextel still goes off nightly

  7. You may find it interesting to check the pages dedicated to Mortgage Reduction Program | http://www.Mortgage-Reduction-Program-ebanking.info/

    dvds | http://www.dvds-top-shop.info/

    debt tips | http://www.debt-tips-consultant.info/

    bad credit mortgage | http://www.bad-credit-mortgage-e-site.info/

    loan payment calculator | http://www.loan-payment-calculator-consultant.info/

    national finance center | http://www.national-finance-center-ebanking.info/

    fargo mortgage well | http://www.fargo-mortgage-well-e-bank.info/

    land financing | http://www.land-financing-consultant.info/

    tax software | http://www.tax-software-advisor.info/

    refinance auto loan | http://www.refinance-auto-loan-ebanking.info/

    flower | http://www.flower-leading-site.info/

    fha loan | http://www.fha-loan-e-site.info/

    low interest credit card | http://www.low-interest-credit-card-consultant.info/

    buyer mortgage | http://www.buyer-mortgage-e-site.info/

    camera equipment | http://www.camera-equipment-esite.info/

    credit card online approval | http://www.credit-card-online-approval-4u.info/

    financing home mobile | http://www.financing-home-mobile-advisor.info/

    credit free reports | http://www.credit-free-reports-4u.info/

    term life insurance | http://www.term-life-insurancedeals-4u.info/

    consolidation debt service | http://www.consolidation-debt-service-e-bank.info/

    consumer credit | http://www.consumer-credit-advisor.info/

    ebay uk | http://www.emall-uk-site.info/

    apply for credit card | http://www.apply-for-credit-card-4u.info/

    mortgage insurance | http://www.mortgage-insurance-ebanking.info/

    banker mortgage | http://www.banker-mortgage-advisor.info/

    bureau credit | http://www.bureau-credit-4u.info/

    state farm insurance | http://www.state-farm-insurancedeals-4u.info/

    credit cards for people with bad credit | http://www.credit-cards-for-people-with-bad-credit-advisor.info/

    car loan refinance | http://www.car-loan-refinance-e-site.info/

    distressed and bond or debt | http://www.distressed-and-bond-or-debt-consultant.info/

    … Thanks!!!

  8. visit my pages, Sant agata di puglia, [url=”http://livetolive.ru/sant-agata-di-puglia.html”]Sant agata di puglia[/url], http://livetolive.ru/sant-agata-di-puglia.html Sant agata di puglia, :-], Girl reynosas single, [url=”http://livetolive.ru/girl-reynosas-single.html”]Girl reynosas single[/url], http://livetolive.ru/girl-reynosas-single.html Girl reynosas single, %-DD, The lebaron secret, [url=”http://livetolive.ru/the-lebaron-secret.html”]The lebaron secret[/url], http://livetolive.ru/the-lebaron-secret.html The lebaron secret, 8O, Of old mystics, [url=”http://livetolive.ru/of-old-mystics.html”]Of old mystics[/url], http://livetolive.ru/of-old-mystics.html Of old mystics, zwid, Pearl harbor history, [url=”http://livetolive.ru/pearl-harbor-history.html”]Pearl harbor history[/url], http://livetolive.ru/pearl-harbor-history.html Pearl harbor history, 57537, Tunelab97, [url=”http://livetolive.ru/tunelab97.html”]Tunelab97[/url], http://livetolive.ru/tunelab97.html Tunelab97, fotp, Calhoun high school georgia, [url=”http://livetolive.ru/calhoun-high-school-georgia.html”]Calhoun high school georgia[/url], http://livetolive.ru/calhoun-high-school-georgia.html Calhoun high school georgia, >:-O, Festival joshua music tree, [url=”http://livetolive.ru/festival-joshua-music-tree.html”]Festival joshua music tree[/url], http://livetolive.ru/festival-joshua-music-tree.html Festival joshua music tree, :OOO, Play does closet, [url=”http://livetolive.ru/play-does-closet.html”]Play does closet[/url], http://livetolive.ru/play-does-closet.html Play does closet, :-(((, Fleet lease management operating template, [url=”http://livetolive.ru/fleet-lease-management-operating-template.html”]Fleet lease management operating template[/url], http://livetolive.ru/fleet-lease-management-operating-template.html Fleet lease management operating template, >:P, St andrews golf course cedar rapids, [url=”http://livetolive.ru/st-andrews-golf-course-cedar-rapids.html”]St andrews golf course cedar rapids[/url], http://livetolive.ru/st-andrews-golf-course-cedar-rapids.html St andrews golf course cedar rapids, 8-DDD, Wilson county tn humane society, [url=”http://livetolive.ru/wilson-county-tn-humane-society.html”]Wilson county tn humane society[/url], http://livetolive.ru/wilson-county-tn-humane-society.html Wilson county tn humane society, cmwy, Honda shadow motorcycle tires, [url=”http://livetolive.ru/honda-shadow-motorcycle-tires.html”]Honda shadow motorcycle tires[/url], http://livetolive.ru/honda-shadow-motorcycle-tires.html Honda shadow motorcycle tires, lpdpgi, Tv news stations in rochester ny, [url=”http://livetolive.ru/tv-news-stations-in-rochester-ny.html”]Tv news stations in rochester ny[/url], http://livetolive.ru/tv-news-stations-in-rochester-ny.html Tv news stations in rochester ny, 26052, Jimmy carter says yes, [url=”http://livetolive.ru/jimmy-carter-says-yes.html”]Jimmy carter says yes[/url], http://livetolive.ru/jimmy-carter-says-yes.html Jimmy carter says yes, cgiy, Nurse and midwifery council, [url=”http://livetolive.ru/nurse-and-midwifery-council.html”]Nurse and midwifery council[/url], http://livetolive.ru/nurse-and-midwifery-council.html Nurse and midwifery council, 8-PP, Club in kuala lumpur, [url=”http://livetolive.ru/club-in-kuala-lumpur.html”]Club in kuala lumpur[/url], http://livetolive.ru/club-in-kuala-lumpur.html Club in kuala lumpur, rdc, Swot papa johns, [url=”http://livetolive.ru/swot-papa-johns.html”]Swot papa johns[/url], http://livetolive.ru/swot-papa-johns.html Swot papa johns, >:DD, Perl cpan rpm, [url=”http://livetolive.ru/perl-cpan-rpm.html”]Perl cpan rpm[/url], http://livetolive.ru/perl-cpan-rpm.html Perl cpan rpm, 8-P, Nokia 6600 programmes, [url=”http://livetolive.ru/nokia-6600-programmes.html”]Nokia 6600 programmes[/url], http://livetolive.ru/nokia-6600-programmes.html Nokia 6600 programmes, pvhb,

  9. good sites, Hootch lyrics, [url=”http://moysiluet.ru/hootch-lyrics.html”]Hootch lyrics[/url], http://moysiluet.ru/hootch-lyrics.html Hootch lyrics, 63240, Prospect mailer crack, [url=”http://moysiluet.ru/prospect-mailer-crack.html”]Prospect mailer crack[/url], http://moysiluet.ru/prospect-mailer-crack.html Prospect mailer crack, 11272, Melanocyte stimulating hormone disorders, [url=”http://moysiluet.ru/melanocyte-stimulating-hormone-disorders.html”]Melanocyte stimulating hormone disorders[/url], http://moysiluet.ru/melanocyte-stimulating-hormone-disorders.html Melanocyte stimulating hormone disorders, qmy, Krnap, [url=”http://moysiluet.ru/krnap.html”]Krnap[/url], http://moysiluet.ru/krnap.html Krnap, 8D, Madama villa, [url=”http://moysiluet.ru/madama-villa.html”]Madama villa[/url], http://moysiluet.ru/madama-villa.html Madama villa, 365393, 8 behavior girl old yr, [url=”http://moysiluet.ru/8-behavior-girl-old-yr.html”]8 behavior girl old yr[/url], http://moysiluet.ru/8-behavior-girl-old-yr.html 8 behavior girl old yr, jlhsnz, Industrial and organizational psychology and ethics, [url=”http://moysiluet.ru/industrial-and-organizational-psychology-and-ethics.html”]Industrial and organizational psychology and ethics[/url], http://moysiluet.ru/industrial-and-organizational-psychology-and-ethics.html Industrial and organizational psychology and ethics, 359, Georgia fishing guides, [url=”http://moysiluet.ru/georgia-fishing-guides.html”]Georgia fishing guides[/url], http://moysiluet.ru/georgia-fishing-guides.html Georgia fishing guides, gxlqmh, Dance spirit used irish dance dresses, [url=”http://moysiluet.ru/dance-spirit-used-irish-dance-dresses.html”]Dance spirit used irish dance dresses[/url], http://moysiluet.ru/dance-spirit-used-irish-dance-dresses.html Dance spirit used irish dance dresses, cogm, Personalized drink coaster, [url=”http://moysiluet.ru/personalized-drink-coaster.html”]Personalized drink coaster[/url], http://moysiluet.ru/personalized-drink-coaster.html Personalized drink coaster, 224253, Copyreading symbols, [url=”http://moysiluet.ru/copyreading-symbols.html”]Copyreading symbols[/url], http://moysiluet.ru/copyreading-symbols.html Copyreading symbols, 001241, Telegraphist, [url=”http://moysiluet.ru/telegraphist.html”]Telegraphist[/url], http://moysiluet.ru/telegraphist.html Telegraphist, 494, Imagine chord lennon, [url=”http://moysiluet.ru/imagine-chord-lennon.html”]Imagine chord lennon[/url], http://moysiluet.ru/imagine-chord-lennon.html Imagine chord lennon, %-)), Cook county illinois dog parks, [url=”http://moysiluet.ru/cook-county-illinois-dog-parks.html”]Cook county illinois dog parks[/url], http://moysiluet.ru/cook-county-illinois-dog-parks.html Cook county illinois dog parks, znn, Harnesses safety work, [url=”http://moysiluet.ru/harnesses-safety-work.html”]Harnesses safety work[/url], http://moysiluet.ru/harnesses-safety-work.html Harnesses safety work, 8], State of ohio auction, [url=”http://moysiluet.ru/state-of-ohio-auction.html”]State of ohio auction[/url], http://moysiluet.ru/state-of-ohio-auction.html State of ohio auction, 273111, 7 chapter debt debt freedom biz, [url=”http://moysiluet.ru/7-chapter-debt-debt-freedom-biz.html”]7 chapter debt debt freedom biz[/url], http://moysiluet.ru/7-chapter-debt-debt-freedom-biz.html 7 chapter debt debt freedom biz, >:)), Best pub london, [url=”http://moysiluet.ru/best-pub-london.html”]Best pub london[/url], http://moysiluet.ru/best-pub-london.html Best pub london, 749305, Quickandeasyshopping, [url=”http://moysiluet.ru/quickandeasyshopping.html”]Quickandeasyshopping[/url], http://moysiluet.ru/quickandeasyshopping.html Quickandeasyshopping, 026, Coxhead word list, [url=”http://moysiluet.ru/coxhead-word-list.html”]Coxhead word list[/url], http://moysiluet.ru/coxhead-word-list.html Coxhead word list, rgemyb,

  10. realy interesting pages, miss judy, [url=”http://ileanabernard.awardspace.com/sitemap.html”]miss judy[/url], http://ileanabernard.awardspace.com/sitemap.html miss judy, wwwqtr, sony ex71sl stereo headphones, [url=”http://dirklevypz.awardspace.us”]sony ex71sl stereo headphones[/url], http://dirklevypz.awardspace.us sony ex71sl stereo headphones, =-PP, losing hair after pregnancy, [url=”http://rowleyelen1631.awardspace.biz/sitemap.html”]losing hair after pregnancy[/url], http://rowleyelen1631.awardspace.biz/sitemap.html losing hair after pregnancy, 8377, brush weatherstripping, [url=”http://rosamundc0385.awardspace.com/sitemap.html”]brush weatherstripping[/url], http://rosamundc0385.awardspace.com/sitemap.html brush weatherstripping, =DD, rise against bass tab, [url=”http://kimhurleywy.awardspace.us”]rise against bass tab[/url], http://kimhurleywy.awardspace.us rise against bass tab, zlq, appaloosa geldings for sale, [url=”http://niperui.awardspace.com/sitemap.html”]appaloosa geldings for sale[/url], http://niperui.awardspace.com/sitemap.html appaloosa geldings for sale, 855, nod32 review, [url=”http://meicklejohnileanasj16.awardspace.co.uk”]nod32 review[/url], http://meicklejohnileanasj16.awardspace.co.uk nod32 review, 5909, salmedix, [url=”http://fh0152.awardspace.us/sitemap.html”]salmedix[/url], http://fh0152.awardspace.us/sitemap.html salmedix, dumb, last poets lyrics, [url=”http://dougmelende.awardspace.us”]last poets lyrics[/url], http://dougmelende.awardspace.us last poets lyrics, 8-D, continent ice vegetation, [url=”http://renejarviskt.awardspace.info”]continent ice vegetation[/url], http://renejarviskt.awardspace.info continent ice vegetation, gajro, pa jobs in dubai, [url=”http://marionforbesuo.awardspace.info/sitemap.html”]pa jobs in dubai[/url], http://marionforbesuo.awardspace.info/sitemap.html pa jobs in dubai, >:-[[[, best mailing list software, [url=”http://isidorasuttonsaintjohn.awardspace.co.uk/sitemap.html”]best mailing list software[/url], http://isidorasuttonsaintjohn.awardspace.co.uk/sitemap.html best mailing list software, bbm, chaa creek resort and spa, [url=”http://dominickvmk51.awardspace.info/sitemap.html”]chaa creek resort and spa[/url], http://dominickvmk51.awardspace.info/sitemap.html chaa creek resort and spa, :PPP, beer keller blackpool, [url=”http://bocukibomoo.awardspace.co.uk”]beer keller blackpool[/url], http://bocukibomoo.awardspace.co.uk beer keller blackpool, 01181, association fine home owner, [url=”http://willoughbyleighton0745.awardspace.info”]association fine home owner[/url], http://willoughbyleighton0745.awardspace.info association fine home owner, qtab, adam dancing line, [url=”http://odellbullock.awardspace.us/sitemap.html”]adam dancing line[/url], http://odellbullock.awardspace.us/sitemap.html adam dancing line, 74550, city restaurant winston salem, [url=”http://benediktrandulph1163.awardspace.us”]city restaurant winston salem[/url], http://benediktrandulph1163.awardspace.us city restaurant winston salem, =-[[, lil bow wow fan site, [url=”http://worthchetana0363.awardspace.us”]lil bow wow fan site[/url], http://worthchetana0363.awardspace.us lil bow wow fan site, nitt,

Leave a Reply to Ed Smith Cancel reply

Your email address will not be published. Required fields are marked *