How to stop making executive project documentation

And start making useful documentation.

The overwhelming majority of IT infrastructure building projects implemented even by very large system integrators have one significant drawback - useless design documentation. No, no, of course, the documentation contains all the necessary data and by reading it you can figure out what was organized and how. Its uselessness is manifested in the further operation of information systems and is expressed in the difficulty of keeping the documentation up to date and the inability to quickly find the necessary information in it. As a result, this project documentation, over time, instead of useful reference material becomes another beautiful and useless reporting document.

In this article, I would like to share with my colleagues some principles of drawing up project documentation, which we use in our work and which, perhaps, will allow your clients to enjoy not only the IT infrastructure built by you, but also to keep the documentation up-to-date and easy on it, for years remembering you with a kind word. Let's start:
')

1) Structure the information

Your document will be read in full, most likely, only at the stage of project delivery. Whether it will be addressed further depends on the ability of the document to give quick answers to short questions: “what does this server do?”, “How does the mail work?”, “What will stop working if I turn off this piece of iron?”. The clear structure of the document greatly simplifies the search for the necessary information. We, for example, adhere to the following structure:

1. General description of the network

2. IT infrastructure

• network hardware
• Physical servers
• Storage systems
• Virtual machines
• Peripherals
• Office equipment
• ...

3. IT services

• Active Directory Domain Services
• WSUS update server
• Deployment Service Workstations WDS Users.
• post office
• Collaboration with documents
• Telephone communications
• Internet access
• ...

4. Application

• Software licenses
• Naming convention
• ...

2) Determine who you are writing for.

Description of the IT infrastructure is one document, the instruction is another. No need to try to fit in one document description of the printing service, instructions on granting access rights to printers and scanning documents on the MFP. It is better to make 3 documents: a description of the IT infrastructure, a technician support manual and a user manual. In this case, the sysadmin, enikeyschik and the user will receive exactly the information that they need without flipping through a bunch of pages of "extra information."

3) Achieve completeness, integrity and consistency of data.

If the documentation you have indicated some technical parameter in the description of the device or server, then it should be specified for all elements to which it is applicable, and, what is equally important, everywhere in the documentation this parameter should be called the same. If you later need to make any changes on the network (for example, change the DNS server address), you can make a complete list of nodes that will also need to change the settings and thereby accurately plan the changes. It seems a trifle, and the benefits of documentation increases significantly.

4) Avoid duplication of information.

So that changes in the IT infrastructure can be easily reflected in your document in the future (and thus keep it up to date) it is necessary that the information in it has to be changed only in one place. Those. the values ​​of the parameters of a server, device or application must be specified for the entire document once. If you in three places in the document indicated that such and such a server has such an IP address, then it is likely that in several years in this document the server will have 3 different IP addresses and your document will lose its original value. Just do not ask me why in such cases, rarely anyone uses the search on the document.

5) Do not describe and advertise technologies, do not use comparative turnovers

Sometimes it seems to me that project documentation in some companies is sculpted based on a commercial offer. The specialists who will read the documentation afterwards, absolutely no matter how abrupt this or that technology was at the time of its introduction, or why the choice fell on it - the project has already been made, and now it only remains to receive information how everything was set up. The phrases of “high availability”, “more flexible”, “increased reliability” are merely personal judgments of the drafter.

6) Increase the concentration of meaning per unit of text: use tables and lists

The worst project documentation that I had to meet resembled an introductory essay. Somewhere on the third page, I merged IP addresses, masks, arrays, user services, and login access passwords. To find the parameter I needed in this documentation, I had to read a few paragraphs of the text, hoping that the next sentence would reach the meaning I needed.
Try to use less unrelated words in the documentation. It is useful to put all meaningful values ​​in the tables, and instead of listing, to make lists — this allows, often just looking around the section, to immediately find the desired parameter.

7) One language of presentation and less bulshit

Not “backup”, but “backup”. Not “Antivirus”, but “antivirus software”. Not “Hot Fixes” (the original style is preserved), but “fix packs”. Here it seems simple things, and the documentation ceases to break a brain when reading.

8) Include full product names.

Are you talking about something like "SUS Server" or "RIS Server"? Before using the abbreviated names of any solution in the documentation as a self-sufficient designation, consider whether it will talk about something to technicians in 5-10 years. For example, where it is more correct to specify these solutions as “SUS update installation server (Software Update Services)” or “RIS (Remote Installation Server) network installation server”. ”

9) Screenshots complement, but do not replace textual information.

In the user manual, where the reader often sees this application for the first time, screenshots are simply obliged to accompany the text. In the documentation on IT infrastructure, where the reader should already know what is being said, the screenshots, in most cases, only take up space without carrying any useful information. But in both cases, screenshots cannot replace textual information. First, they still do not see anything, especially after printing the document. Secondly, changing the settings will require taking a repeated screenshot to keep the document up to date. And most importantly - the values ​​in the screenshots can not be found through the search on the document.

10) Use visuals and photographs of equipment

The functional network diagram, the location of the equipment in the rack and what the equipment itself looks like is not so difficult to do and add to the document now, but it greatly simplifies finding the right piece of hardware after 5-6 years, when not every admin can tell what the HP Proliant G8 server looks like 2014 release.

11) Read the written documentation carefully. Check the text for errors!

Turnovers of the form “Centralized printing of users in the Moscow office of the Customer using the Network Printer service” performed by market leaders sometimes makes you wonder whether I know a lot about the possibilities of IT technologies. Well, on the spelling and punctuation errors, I generally keep quiet, although I myself had a troika in Russian. Before sending the document to the client, add a couple of words to it in different places and give it to the person more or less aware of the grammar. If he finds all your bookmarks - the work is done well, but the main thing is not to bend with the use of obscene words in the bookmarks - sometimes the documentation goes with them to the clients.

Successes!

Ivan Kormachev
Company "IT Department"
www.depit.ru