Overview project documents and sheets

Documentation is the keystone for the ICT and yet many people dislike the task of documenting. Unfortunately a lot of documents must be created and maintained. IF not the operation and projects do run a high risk of malfunctioning.  And the organisation could be in jeopardy. What type of documents must be created and what are the concerns of each of these documents?

Overview type of documentation and sheets used in ICT projects

  • White paper – WHP
    • Definition: A white paper is an authoritative report or guide that informs readers concisely about a complex issue and presents the issuing body’s philosophy on the matter. It is meant to help readers understand an issue, solve a problem, or make a decision.
    • Source group: Marketing / Sales
    • Target group: Potential customer. Influencing and persuading customer.
    • Concerns: The white paper has only an added value if it is written in a non-commercial way, verifiable and written by independent researchers. Fact checking is important.
  • Leaflet – LFT
    • Definition: A leaflet is a small sheet, flat or folded, of printed material meant to provide information or advertisement. Folder is larger than Leaflet and contains more information.
    • Source group: Marketing / Sales
    • Target: Potential customer. Influencing and persuading customer.
    • Concerns: The white paper has only an added value if it is written in a non-commercial way, verifiable and written by independent researchers. Fact checking is important.
  • Proposals – RFP/RFI
    • Definition RFI: A request for information (RFI) is a standard business process whose purpose is to collect written information about the capabilities of various suppliers. An RFI is primarily used to gather information to help make a decision on what steps to take next.
    • Definition RFP: A request for proposal (RFP) is a document that solicits proposal, often made through a bidding process, by an agency or company interested in procurement of a commodity, service or valuable asset, to potential suppliers to submit business proposals.
    • Source group: Vendor
    • Target: Business and ICT . The requirements must be clear and met. A full understanding is necessary. Starting point of a project. Designs and / or solutions are based on full understanding of the requirements.
    • Concerns: The RFI/RFP has only an high added value if all requirements are properly collected, discussed and analysed so a solid solution can be developed against acceptable quality and budget. The requirements phase is the most crucial phase. It is hard to get a clear understanding and in too many cases not done properly.
  • Statement of work – SOW
    • Definition: A Statement of Work (SOW) is a document routinely employed in the field of project management. It defines project-specific activities, deliverables and timelines for a vendor providing services to the client. The SOW typically also includes detailed requirements and pricing, with standard regulatory and governance terms and conditions. It is often an important accompaniment to a Request for Proposal (RFP).
    • Source group: Vendor
    • Target: Business and ICT. The requirements must be clear and met. A full understanding is necessary. Starting point of a project. Designs and / or solutions are based on full understanding of the requirements.
    • Concerns: The SOW has only an high added value if all requirements are properly collected, discussed and analysed.
  • High level design (System/Software/Service) – HLD
    • Definition:High-level design (HLD) explains the architecture used for developing a solution (infrastructure or software). The architecture diagram provides an overview of an entire system, identifying the main components that would be developed for the product and their interfaces. The HLD uses technical terms that should be understandable to the system matter experts of the system.
    • Source group: Architects and / or vendor.
    • Target: Business, System matter experts, testers, project
    • Concerns:  There is mostly a bad traceability between the requirements and components of the solution. Furthermore there is NO clear template or format of a good design. Every IT house or vendor has its own way. There is no best practices even though there is TOGAF.
  • Low level design, technical design or as-buidld (System/Software/Service) – LLD
    • Definition: Design (LLD). Contains the technical details required to implement that particular solution.
    • Source group: System matter experts.
    • Target: Other system matter experts and Administrators.
    • Concerns: It is the most important document of the project, and it oftentimes needs consulting even after the implementation. The major concern is that the technical requirements between the various disciplines of the infrastructure are not properly set or not known.
  • Work packages (Project plan and progress report) – WRP
    • Definition: Unit of work or job that is clearly distinguishable from other such work packages, has scheduled start and completion dates with interim milestones as applicable, has a relatively short time span subdivided to facilitate measurement of work performed, has an assigned budget, and (is integrated with the schedules of related work packages.
    • Source group: (Solution) Architect.
    • Target: Project management.
    • Concerns: The scope is poorly determined and the planning is too detailed and often a lot of adjustments must be made due to new insight information. As a result often scope changes and budget changes are requested.
  • Work procedures – WPR
    • Definition: A fixed, step-by-step sequence of activities or course of action (with definite start and end points) that must be followed in the same order to correctly perform a task. Repetitive procedures are called routines. Remark: Instruction is a detailed work description of how procedures should be performed.
    • Source group: Administrators, functional managers, SME’s.
    • Target: End-users / super users of the business or Administrators, SME’s, Managers.
    • Concerns: Work procedures are written often too high level or sometimes too detailed. Furthermore work procedures are written to fast. Procedures should be checked out over time and written over a reasonable period of time to cover important aspects.
  • Admin guides – ADM
    • Definition: An admin guide is a guide describing the features, installation, configuration, management, planning and deploying of a system/server or other infrastructure component.
    • Source group: Technical specialists, administrators or SME’S.
    • Target: Project as part of the delivery of documents, other administrators
    • Concerns: When written by a vendor, in most cases, they are properly written but if it is done by internal employers in many cases the admin guide often too detailed. It is in most cases a combination of installation and configuration, user guide and contains a lot of sheets with administrative details.
  • User guides – USR
    • Definition: A user guide gives an overview of how to use the system. It contains a Short introduction or overview of the system, brief technical details of the hardware and software requirements to run the system, a Glossary of technical term and troubleshooting which is a list of things to check before getting help.
    • Source group: SME’s, Administrators, functional managers, application managers.
    • Target: (End) users of the business.
    • Concerns: 
  • Planning guides – PLN
    • Definition: A basic management function involving formulation of one or more detailed plans to achieve optimum balance of needs or demands with the available resources. The planning process identifies the goals or objectives to be achieved, formulates strategies to achieve them, arranges or creates the means required, and implements, directs, and monitors all steps in their proper sequence.
    • Source group: SME’s
    • Target: (Project) Management, other SME’s/Administrators
    • Concerns: The planning is often too detailed and discussed as an isolated planning without taken into account the dependencies with other project and plans. And mostly the planning does not take into account the advancing insight. As result, the planning must be altered too often.
  • Deployment guides – DEP
    • Definition: It defines the sequence of operations or steps that must be carried to deliver changes into a target system environment. The operations within a deployment guide can be executed manually or automatically. Deployment guides are usually well defined and approved prior to the deployment date. In situations where there is a high potential risk of failure in the target system environment, deployment guides may rehearsed to ensure there are no issues during actual deployment. Structured repeatable deployments are also prime candidates for automation which drives quality and efficiency.
    • Source group: SME’s/Administrators
    • Target: Business (users, departments), ICT, Project members, SME’s/Administrators
    • Concerns: A large full blown deployment of software and/or infrastructure components has a low to poor result due to the many unforeseen problems that are occur during the deployment.
  • Migration guides (data / infrastructure / software) – MIG
    • Definition: The purpose of a migration guide is to provide the project information about the impact and consequences of the migration and what a migration project entails, and the steps / actions to take to prepare, execute and wrap-up (after care) the migration in a (very) detailed way with the intention to avoid interruption of the operations.
    • Source group: Migration specialists,
    • Target: SME’s / Administrators, Project (manager and members).
    • Concerns: 
  • Work books or run books – RUN
    • Definition:  In computer systems and networks a run book is a set of defined procedures, actions or steps developed by the administrator or IT professional for maintaining the everyday routine or migration purposes. The run book should contain all the information a staff or migration team would need to perform daily operations or the migration. Also the work book give guidelines how to to deal with any problems that arise during usage from the operational system or network or during the migration. Some procedures defined in an organisation’s run book would include procedures such as for starting and stopping the system, instructions for handling special devices, such as mounting optical disks or tapes, and procedures for how to perform backups, and so on.
    • Source group:
    • Target:
    • Concerns: Tools.
  • Test plans and test scripts – TST
    • Definition: Test plan is the project plan for the testing work to be done. It is a test design specification, a collection of test cases and  a set of test procedures or another definition is a document that outlines the product functions to be tested, what specific tests will be performed, the approach to be take for those tests, what to test and what not to test, how the tests will be performed, who will be responsible for performing each test, what results are expected, what is considered a successful test and a failed test, and exit criteria for any series of tests as well as for the testing phase as a whole;
    • Source group: Testers (functional, technical);
    • Target: Management business/ICT, project members, SME’s/Administators, auditors and security specialists;
    • Concerns:  No good clarity on the requirements, traceability to the requirements are often bad, too many assumptions, on good interaction between testers and specialists/experts.
  • Training guides – TRA
    • Definition:
    • Source group:
    • Target:
    • Concerns: 
  • Reports (Error, audits, incidents, problems, performance, failover ……)
    • Definition:
    • Source group:
    • Target:
    • Concerns: 
  • Service catalogs
    • Definition: A service catalog (or catalogue), is an organized and curated collection of any and all business and information technology related services that can be performed by, for, or within an enterprise.Service catalogs act as knowledge management tools for the employees and consultants of an enterprise, allowing them to route their requests for and about services and services related topics to the subject matter experts who own, are accountable for, and operate them. Each service within such service catalogs is usually very repeatable and has controlled inputs, processes, and outputs.
    • Source group:
    • Target:
    • Concerns: 
  • Sheets
    • Defect sheets, Data sheets, Configuration sheets, Diagrams, tables and maps, Master sheets, Fact sheets

Major concerns

  1. Writing is a skill and sometimes it is form of art. Most engineers do not possess the skill to write or reluctant to write.
  2. Sometimes some documents require a high degree of precision. Words should exactly describe the intentions, goal, functions etc. Too often the words are vague, the structure of the documentation is poor, the style is wrong, the punch line or bottom line is missing. The words do not support a table or diagram or vice versa.
  3. Architects write sometimes in a theocratical or academic way without challenging their design or solution. The best way to challenge your own design is to execute it!
  4. Only a handful people read and here you a fundamental problem. Training and awareness programs, continues guidance is needed to get people reading. And of course reading is a skill too. Teaching how to read, especially nowadays where we are overloaded by information!
  5. Too many changes happen during writing and change management procedures are often poor. Discipline is the answer here.
  6. Peer review is too often not done or not done properly. This is often due to lack of resources.
  7. Poor access to storage and retrieval systems. Hiring a truly librarian (which is a job) is really needed!
  8. Poor versioning of documents.
  9. Documentation almost never reaches its final version due to lack of time or just plain carelessness.  The value of documentation is underestimated.
  10. Documentation is seen as a burden, a necessity, a closing entry. There is no overall responsible person.
  11. References to other documentation, to requirements of whatever is often (very) poor.