How to stop making project design documentation

    And start making useful documentation




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

    In this article, I would like to share with my colleagues some principles of compiling project documentation that we use in our work and which, perhaps, will allow your customers to enjoy not only the high-quality IT infrastructure you built, but also easily and naturally keep the documentation up-to-date on it, remembering you with a kind word for years. Proceed:

    1) Structure information

    Your document will be read in full, most likely, only at the stage of delivery of the project. Will they turn to him in the future, depending on the ability of the document to give quick answers to short questions: “what does this server do?”, “How does mail work?”, “What will stop working if I turn off this piece of hardware?”. The clear structure of the document greatly simplifies the search for the necessary information. For example, we 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
    • WDS User Workstation Deployment Service.
    • post office
    • Collaboration with documents
    • Telephone communications
    • Access to the Internet
    • ...

    4. Application
    • Software licenses
    • Naming convention
    • ...

    2) Determine who you are writing the document for

    Description of IT infrastructure - one document, instructions - another. Do not try to fit in one document a description of the print service, instructions for granting access rights to printers and for scanning documents on the MFP. It is better to make 3 documents: a description of the IT infrastructure, technical support specialist instructions and user instructions. In this case, the system administrator, enikeyschik and user will receive exactly the information that they need, without turning over a bunch of pages of "extra information".

    3) Achieve completeness, integrity and uniformity of data

    If some technical parameter is indicated in the documentation in the description of the device or server, then it must be specified for all elements to which it is applicable, and, no less important, everywhere in the documentation this parameter should be called the same. If in the future you need to make some changes in the network (for example, change the address of the DNS server), then by a simple search on the document you can make a complete list of nodes on which you will also need to change the settings and thereby accurately plan the changes. It seems to be a trifle, but the benefits of documentation increase significantly.

    4) Avoid duplication of information

    So that changes in the IT infrastructure can be easily reflected in your document in the future (and thereby 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 indicated once for the entire document. If you indicated in three places in a document that such a server has such an IP address, then it is likely that after a few years in this document the server will have 3 different IP addresses and your document will lose its original value. Just don’t ask me why, in such cases, rarely does anyone use a document search.

    5) Do not describe or advertise technology, do not use comparative momentum

    Sometimes it seems to me that the project documentation in some companies is sculpted on the basis of a commercial offer. For specialists who will read the documentation later, it doesn’t matter how cool this or that technology was at the time of its introduction, or why the choice fell on it - the project has already been completed, and now it remains only to get information on how everything was set up. The phrases of “high availability”, “more flexible”, “increased reliability” are just personal evaluative judgments of the compiler.

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

    The worst project documentation I had to meet was like an opening essay. Somewhere on the third page, IP addresses, masks, arrays, user services, and access logins and passwords merged together. To find the parameter I needed in such documentation, I had to read several paragraphs of the text, hoping that in the next sentence we would get to the value I needed.
    Try to use fewer non-topic words in the documentation. It is useful to make all the relevant values ​​in the tables, and instead of listing to do lists - this allows, often just looking around the section, immediately find the desired parameter.

    7) One language of presentation and less bulshita

    Not “backup”, but “backup”. Not Antivirus, but Antivirus Software. Not “Hot Fixes” (the original style is preserved), but “fix packs”. Here it seems to be simple things, and the documentation stops breaking your brain when reading.

    8) Indicate the full names of the products

    Are they saying something about SUS Server or RIS Server now? Before using the abbreviated names of a solution as documentation in a documentation as a self-sufficient designation, think about whether it will talk about something to technical specialists in 5-10 years. For example, it’s much more correct to indicate these solutions as “SUS (Software Update Services) installation server” or “RIS (Remote Installation Server) network installation server”.

    9) Screenshots supplement but do not replace text information

    In the user manual, where the reader often sees the application for the first time, screenshots are simply required to accompany the text. In the documentation for the IT infrastructure, where the reader should already know what is at stake, screenshots, in most cases, only take up space without carrying useful information. But in both cases, screenshots cannot replace textual information. Firstly, they still can’t see anything, especially after printing a document. Secondly, changing the settings will require taking a second screenshot to maintain the relevance of the document. Well and most importantly - the values ​​in the screenshots cannot be found through a search on the document.

    10) Use visual diagrams and photos of equipment

    The functional diagram of the network, the location of the equipment in the rack and how the equipment itself looks is not so difficult to add and add to the document now, but it greatly simplifies the search for the necessary 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 at the Moscow office of the Customer is carried out using the Network Printer service” performed by market leaders sometimes makes you seriously think about how much I know about the capabilities of IT technologies. Well, I’m generally silent about spelling and punctuation errors, although I myself had a triple in Russian. Before sending a document to a client, add a couple of words and bookmarks to it in different places and let it read to a person who more or less understands the grammar. If he finds all your bookmarks - the work is done well, but the main thing is not to go too far using obscene words in the bookmarks - sometimes the documentation leaves with the clients along with them.

    Good luck!

    Ivan Kormachev
    IT Department Company
    www.depit.ru

    Also popular now: