Published: 10 Aug 2009
As an experienced Exchange administrator, I've never found documenting an Exchange installation to be particularly exciting. Not only can it be repetitive, trying to decipher handwritten changes and knowledgebase articles isn't much fun either.
But administrators have an obligation to document, explain and provide guidance for others who will work with the system. Exchange architects often leave sites when an installation is complete, so providing proper documentation is essential.
There are a few principles of good documentation that you should follow. Consider using this structure and some of these methods when creating your own Exchange Server installation documentation.
Identify your audience
From the beginning, establish who will read the documentation. It's easy to assume that the people who will benefit from your work are devout Exchange admins. But since Exchange 2007 split management of user mailboxes and accounts between the Exchange Management Console, Exchange Management Shell and Active Directory users and computers, an organizations in which the Help Desk team created accounts needs its own documentation.
The documentation may help to explain scripts that were used to complete the process or to define the nuances between the Exchange Management Console and Exchange Management Shell. No matter what its purpose is, the documentation is key.
In these types of situations, you need to split your documentation into two separate parts. Technical information may contain details that you don't want unqualified people to access.
You should also ask if your users need any documentation, such as how to use Outlook Web Access. Some companies want to include information on message limits and common NDR (DSN) in documentation for users.
Finally, mind your acronyms. You may be able to get away with three-letter acronyms in highly technical documents, but users may not be familiar with jargon. User documentation should be succinct and to the point.
Structure the document logically
Your document structure should be easy to navigate; information contained in it should be easily accessible. It's essential to include contents pages, indexes, explanatory headings and sequential titles.
When structuring my Exchange documentation, I like to start with the Dependency Grounding Approach. In this approach, I subjectively look at all component parts that make up the entire Exchange installation.
In order for a system to exist, it needs a purpose -- often called the PID in Project Management. To determine the purpose, there must be an objective -- what the end project will look like and what it will accomplish. You must formulate a Summary Solution to achieve an objective.
Of course, this is merely a preamble to important details. Don't spend too much time on this portion. This usually serves as an overview for auditors when they look at your documentation. A common question an auditor may ask is: What is the purpose of this manual?
A major portion of the documentation follows the Dependency Grounding Approach:
- Exchange configuration Information -- This is vital and should contain all Exchange-related configuration information.
- Hardware -- Detailed documentation on your hardware platform is useful. Some examples might include: How fiber is connected on the SAN; relationships between fiber switches, SANS and FC-AL cards; drive enclosures; disk types; etc.
- Supporting infrastructure -- Exchange has many dependencies such as Active Directory and networking. It's helpful to provide documentation on these elements since they give an overview of how your Exchange solution is structured.
Maintain document consistency
When you have two or more people are documenting an environment, there may be differing styles. One common scenario could be in a Unified Messaging environment in which a telephony worker is also integrating Exchange into a PBX. It's important that documentation maintains a consistent writing and formatting style, while also maintaining structure.
When working with others, meet at least once and designate a person to compile the final documented product, as well as the structure, format and style.
This might seem obvious, but I've seen documentation that was prepared by several people that seemed cobbled together at the last minute. It didn't seem to flow, and grammar and phrasing were inconsistent. For example, on writer might use the term SAN Certificate while another uses UCC.
Since you probably will write the document over several days, maintain the same writing style. Make sure that your style is consistent from one day to the next.
It's also imperative to format objects, such as section titles, consistently. Think about how you want to format code snippets, actions within interfaces, etc., before writing, for example [ START -> RUN = Ping <Server Name> ].
At this point, you should have a conceptual bare bones structure of your documentation. It will progress further once you add in the title page, copyright information, bibliography and a table of contents.
author: Andy Grogan is an Exchange MVP based in the UK. He has worked in the IT industry for the last 14 years working primarily with Microsoft, HP and IBM technologies. His main passion is Exchange Server, but he also specializes in Active Directory, SQL Server and Storage solutions. Andy is currently working for a large council in West London as the Networks and Operations Manager supporting 6,000 customers on over 240 sites. You can visit Andy's website at http://www.telnetport25.com/.
Do you have comments on this tip? Let us know.
Do you know a helpful Exchange Server, Microsoft Outlook or SharePoint tip, timesaver or workaround? Email the editors to talk about writing for SearchExchange.com.