Open IT Forum: What should system documentation look like?

6,345 pts.
Tags:
AS/400
Business Intelligence
Channel
CIO
CRM
DataCenter
Development
Linux
Lotus Domino
Microsoft Exchange
Microsoft Windows
Mobile
Networking
Open IT Forum
Oracle
SAP
Security
SQL Server
Storage
System Documentation
Virtualization
VoIP
Windows Server
While documentation doesn't necessarily make the world go 'round, it certainly keeps it spinning neatly on its axis when trouble arises. If you're providing a product or service, you should be providing your customers with accurate information that allows them to effectively use and maintain that product, which translates into accurate and thorough documentation. So tell us, what are your own processes for system documentation? Share with us what it looks like, what your obstacles are, and what you've found works for you. For more information, check out 5 Things Your System Documentation Should Be Parts One and Two. Then leave your two cents. Contribute to this living document, and we'll give you a whopping 150 Knowledge Points.
ASKED: August 31, 2011  8:11 PM
UPDATED: March 31, 2012  5:17 PM

Answer Wiki

Thanks. We'll let you know when a new response is added.

My documentation is written to be understood by the least knowledgable person who will be using it. If I’m writing disaster recovery procedures, they are written to be understood by the least qualified and knowledgable person in our department. This is no means a reflection on their abilities, but simply an opinion that if they are able to comprehend and follow the procedures then anyone in the department can. This is necessary as in a true disaster situation they may be the only person(s) available to bring the company back online. Backup procedures are written on an Operator level, system build documentation is written on a junior administrator level, and so on. Whatever the documentation, when it is completed it is given to the aforementioned individual to run through in the test lab. Any problems and misunderstandings are indentified then and revised. The documentation should then be reviewed periodically to insure that it remains current through patches and upgrades.

Discuss This Question: 16  Replies

 
There was an error processing your information. Please try again later.
Thanks. We'll let you know when a new response is added.
Send me notifications when members answer or reply to this question.

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy
  • EAJewett
    Maybe you include this in your Programmer section, but Interface points seem to be one of the critical places we have to go back to long after project team members have scrubbed their memories. "We were using this field one way and now the vendor says that a key report requires us to use it differently. What field in the interface need to be examined and what are our other options to convey the data?" I can see this ideally tying back to the data dictionary "field Admit_Origin has these attributes and informs process A, with an alternate meaning to process B." In any case, building as you go is critical, with documentation of design or process decisions. By the time you are implementing, some of the key people may have changed and the "why are these two departments reflected as one in this process but two in the other?" type questions are killers. There may have been a very good reason for a decision but without that rationale, you are nearly doomed to repeat the discovery and very likely hit the condition that was carefully avoided before.
    615 pointsBadges:
    report
  • TomLiotta
    If you're providing a product or service, you should be providing your customers with accurate information that allows them to effectively use and maintain that product... Especially during the past five years, I've seen a trend where that has become more difficult. More and more, I'm finding our phone support people talking with customer staff who barely know the basics of administering system components much less any sophisticated product. A decade ago, we wouldn't need to describe how to locate a joblog. Now we almost need to include a basic definition of what "joblogs" are before explaining how to cause them to be generated, how access is different for active jobs and completed jobs and where a spooled joblog will be. We're finding a much greater need to include elements of platform documentation that customer staff was expected to know a short time earlier. How does one determine what the line is between "product documentation" and "system documentation"? Tom
    125,585 pointsBadges:
    report
  • EAJewett
    Good point, though as someone who has been pulled out of position to cover products or processes well outside my expertise, I see the pain of both sides. The inexorable grind of "do more with less" takes a toll on both supporters and supportees. I wouldn't expect even the best product documentation to go into platform operation details, and see that as a truly unwinnable proposition. For those of us swimming because we were dropped in the deep end, a bibliography could help shore up those weak points without becoming a maintenance nightmare for those producing the documentation.
    615 pointsBadges:
    report
  • MelanieYarbrough
    [...] Get in on the discussion in our Open IT Forum. [...]
    0 pointsBadges:
    report
  • CharlieBrowne
    I have a few pet peeves with the way IT in general handles documentation. The first one is that programmers do the documentation. If only another program is going to look at it, then this may work. But if a “real” person is going to successfully use it, then it should be written by someone that has the writing and formatting skills. This is really a left brain, right brain thing. I know very few programmers that have both skill sets. I am definitely not one of them. Programmers also assume that the reader will have much of the know that the developer had when creating the application. The second one is what was mentioned regarding making documentation a low priority and giving little time to accomplish it. To me, the solution is to invest in a person or team of people whose sole purpose is to develop and maintain the documentation. This provides consistency, high quality, and guarantee of completeness. Charlie Browne
    39,790 pointsBadges:
    report
  • MelanieYarbrough
    Thank you for the thoughtful input. I've added the points so far, but keep the ideas coming! Thanks, Melanie
    6,345 pointsBadges:
    report
  • MelanieYarbrough
    [...] We’ve received some great responses from EAJewett, TomLiotta, and CharlieBrowne on what system documentation should look like, but we’re still looking for more! (Earn 150 Knowledge Points for [...]
    0 pointsBadges:
    report
  • Connie14K
    As an OS Admin (UNIX) supporting numerous applications, data stores, and databases and as an old COBOL programmer, I also have been put in a position of supporting very old applications, not COTS, but code written by different people throughout the application lifetime. I have always written documentation (Programmer Annotations. Technical Guidance, or Instructions) as I am working through each application/program install or upgrade. I actually did this to help me understand the concepts and get through a difficult procedure... just in case I needed to do it again. I found that ultimately, my documentation was passed onto the next programmer or admin to help them understand. Documentation should NOT be hidden - it should be made available to all who support or use an application or program or Operating System regardless of the fact that it may be too complex/confusing... let the person who reads it determine that. I have tried to write documentation for the user or a newbie. I have heard some say that it's too simplistic for admins, but I don't tend to care. There is no room in my life for elitism or smugness. Besides, it gives the next admin a good foundation for understanding. From that, they can add to the documentation and maintain it as a "living" document.
    160 pointsBadges:
    report
  • Meandyou
    Many good points have been raised. And I'd bet that we all know all of those points. Problem is, we just don't follow thru - for a number reasons (read that as excuses). I will try to remember this discussion next time I need to add to some doc.
    5,220 pointsBadges:
    report
  • EAJewett
    I was lucky enough that a previous employer brought in local university resources for a technical writing course - a full semester over our lunch hours. That is certainly less likely in today's economy, but I think the investment paid off for them. Even we "left-brain-types" can benefit from it, even if it is to build a recipe to follow, as unnatural as it may feel, to produce documentation understandable by someone outside our specialty. Echo Connie14K's point of make it accessible - you cannot always predict who needs the information or who might leverage that information for an improvement.
    615 pointsBadges:
    report
  • James Murray
    I was lucky to have a good college program that required a technical writing course and a lot of good mentors in the beginning of my career. Often documentation is poor because there really is no standard that we train technical people to follow. Unless you've worked with or as a technical writer there's no consideration for writing formats, conventions, etc. I've made a lot of money cleaning up databases where nobody defined how to write Suite... or is it ST ... or STE... or # or... well it goes on and on. I've seen where addresses put in first name fields and many, many other data entry problems. So it's not surprising that a technician isn't able to document their own stuff. When writing documentation I think the first and most important thing to understand is who the audience will be who is reading the documentation. Non-technical users... System administrators... or someone in between. I'll document the audience in most documents I create. Next I'll create the Purpose of the document. Is this a step by step process document, or just a high level briefing on a problem? Perhaps this is a change control log or a troubleshooting ticket that will need to be read by the next support tier above me? When I am studying documentation I'll actually take notes for myself. I'll highlight commands that worked as I'm working through the process... I'll read back a few steps when I'm on a goose chase... then when I have the process down, I'll erase erroneous pieces and test my documentation again. Project proposals are the most interesting documentation to create. Here the technology needs to be accurate, but the conclusion will need to be presented to a manager whose concentration level is about 30 seconds. Converting the reporting from technical into business language and using keywords he understands can make or break a new project proposal. I think the rules should be A) This is boring technical writing not creative writing B) Always document the same way over and over again C) Imagine what your audience is looking for and only share what they need D) Quality control - Have someone check and edit documents for content, grammar and continuity. E) Create a style sheet and forms that reduce the need to write anything. Check boxes, radial buttons and drop down boxes for the most common situations. Avoid text boxes... F) Always document digitally, into a database whenever possible in order to take advantage of search options. G) Oh... Have I mentioned consistency yet? I'd also like to put in my 2 cents in for internal Wicki’s that allow documentation by amateurs that can be quickly edited by experts.
    1,795 pointsBadges:
    report
  • TomLiotta
    ...the first and most important thing to understand is who the audience will be who is reading the documentation. Non-technical users… System administrators… or someone in between. That brings an interesting (to me) point. What good does knowing the audience do for a writer? Say that one document will be for "Non-technical users" and another document will be for "System administrators". A writer is tasked with both documents. Should the same writer be expected to create the same quality of document for two different audiences? I assume that most of my product documentation will be used by someone close to the "System administrators" group. The purposes of the products tend to be aligned with those job functions. After almost 40 years in programming, it's difficult for me to get into a "Non-technical users" mindset. Many words are so familiar to me that they don't ring alarms to me when I use them. I simply don't 'know' that "Non-technical users" won't know what the words mean. The words are common knowledge... right? Well, of course they aren't. But it can be tricky finding a balance, especially when "Writer" isn't your occupation in the first place. So, what good does it do to know the target audience when you are certain to have a different "language set" from anyone who isn't in your particular group? Maybe the good that it ought to do is that writing tasks should not be assigned in the first place to someone not in the target audience group. (Apologies for the two "nots".) If you aren't comfortable with the language of the target audience, maybe you shouldn't be writing for that audience. Tom
    125,585 pointsBadges:
    report
  • HMSSL2K
    Most documentation is never kept up to date. People write it, people come, people go, process's change or new process's take it place, same old documentation.
    3,175 pointsBadges:
    report
  • KFaganJr
    I've been a huge supporter of documentation for a long time. It can seem like an impossible task to get others on board. I've learned that creating my own documentation then bringing it public for triage, updating in post mortem meetings, when training new users or for display to supervisors in other departments to demonstrate our attention to detail has brought good attention to the benefits documentation brings as well as keeping them live documents. Good documentation
    • Avoid duplicates early and try to get individual's documentation to start being a departmental value. Centrally locate documentation, encourage users saving in a similar method and not copying to their own storage to edit or save.
    • Always discuss documentation when performing a post mortem meeting after issues
    • New systems and employees are the perfect oppurtunity to create documentation on, especially since there will be questions that have to be answered several times due to inexperience
    • include the purpose of the document, documentation storage location, or documentation project in a highly visible area so there is no question about what they should accomplish. Then review whether this purpose is met when the documentation is utilized
    • Include the why when documenting installs and troubleshooting. You'll teach other staff more about the purpose of each step and provide an explanation in the event things go wrong or the steps are used for a similar but not exact situation
    I'll add more as it comes to me
    1,355 pointsBadges:
    report
  • MelanieYarbrough
    [...] Open IT Forum: What should system documentation look like? [...]
    0 pointsBadges:
    report
  • wmkelly
    This article describes a very nice framework for managing documentation and is much appreciated. One of the things that my team has found difficult is to keep documentation updated after it is written. Baseline configurations change, and this documentation needs to be updated periodically. Our team has an excellent change management process, but it has not always translated into documentation changes. Our plan is to create a documentation database that is linked to our change management database. In short, when a change request warrants updated documentation, the person performing the change will be prompted to update documentation at the same time. Hopefully, this simple action will help us all keep updated.
    60 pointsBadges:
    report

Forgot Password

No problem! Submit your e-mail address below. We'll send you an e-mail containing your password.

Your password has been sent to:

To follow this tag...

There was an error processing your information. Please try again later.

REGISTER or login:

Forgot Password?
By submitting you agree to receive email from TechTarget and its partners. If you reside outside of the United States, you consent to having your personal data transferred to and processed in the United States. Privacy

Thanks! We'll email you when relevant content is added and updated.

Following