Documentation 101: How to Properly Document Your Cloud Infrastructure Project

In today's rapidly evolving technology landscape, cloud infrastructure has become an indispensable part of modern business operations. To manage this complex infrastructure, documenting its setup, configuration, and ongoing maintenance is critical. Without proper documentation, it becomes challenging to scale the infrastructure, onboard new team members, troubleshoot issues and ensure compliance. 

At Provectus, I have witnessed the advantages of handing over projects with proper documentation and how it allows successful transition and preserves customer satisfaction. 

Whether you are an active engineer, an engineering team leader, or a demanding user of cloud infrastructure, in this article, I will help you to understand the importance of documentation and offer some easy steps for implementing best practices.

Why Is Documentation Important?

Documentation is a key feature that allows for the consistent maintenance of any process. It is a storehouse of intelligence that can be accessed for future reference and replicated if needed.  For example, if an engineer or anyone in the organization has performed, tested, and improved a process, failure to document it would be a waste of intellectual capital and a loss to the organization. 

Documentation is important for many reasons: 

• It helps to keep processes and systems up to date for usage
• It helps with the onboarding and training of new team members
• It helps to improve security by imposing boundaries
• It functions as a means of proof for audits
• It provides a starting point when documenting from scratch
• It helps to continuously improve processes

Documenting your cloud infrastructure is imperative for its smooth and efficient operation.  

What Should Be Documented for Cloud Infrastructure?

In the past, building a computing infrastructure required huge investment and vast planning, taking into consideration the required expertise in the field and the needs of your organization. Once servers and hardware were purchased, it was very difficult to make any significant changes. 

The cloud brought with it significant improvements, making it much easier and more feasible to implement the infrastructure. But still, the ability to make changes and improvements is highly dependent on accurate documentation. 

Following is a basic list of requirements for documentation to ensure that your cloud infrastructure is easy to use and update.

Architecture Diagrams 

An architecture diagram is a visual representation of cloud components and the interconnections that support their underlying applications.

The main goal of creating an architecture diagram is to communicate with all stakeholders — clients, developers, engineers, and management — using a common language that everyone can understand.

To create a diagram, you need a list of components and an understanding of how they interact. You may need to create multiple diagrams if the architecture is complex or if it has several environments. There are user-friendly tools to help you with this first step, many of which are free. For example, Diagrams.net (formerly Draw.io), Miro, SmartDraw, Lucidchart, and others.  

Creating an architecture diagram will help with future planning and design when you are ready to improve the infrastructure. It will help you to easily spot issues or areas that need improvement.

Your diagram can also help with troubleshooting. Engineers will be able to use it to detect flaws in the system and discover their root causes. It will also help with compliance and security requirements.

How-To Instructions

Your infrastructure will likely host many features and applications that require specific steps for access. How-to instructions provide end users with a detailed step-by-step guide that streamlines various processes and saves time. Such instructions are sometimes referred to as detailed process maps, DIYs (do it yourself), walkthroughs,  job aids, tutorials, runbooks, or playbooks. 

Some examples of processes that can benefit from how-to instructions include:

• How to request access for developers
• How to subscribe to an SNS topic
• How to rotate IAM Access Keys
• How to retrieve ALB logs

Policies 

Your cloud infrastructure will have its own policies, whether they are predefined by the IT department or created in collaboration with different teams. Some policies that can be documented include:

1. Access policies: What security measures are in place, and what is required for various individuals, groups, or roles to gain access? What are the premises and procedures for access removal? Are we compliant with the least privilege access best practice?
2. Security policies: Protective policies for management, practices, and resources for data in the cloud. 
3. Data privacy policies: Data must be classified and collected in ways that keep it secure and protected from unauthorized access.
4. Compliance policies: Which regulations and auditing processes must be complied with to use cloud services? What are the responsibilities of Infrastructure team members?
5. Incident and change management: Define the necessary steps to respond to incidents and changes; define outage prioritization, SLA response time, ownership, and post-mortem processes.
6. Monitoring: Along with incident management, there should be documentation of monitors and channels in place to ensure that the infrastructure is up and running. Monitoring is a 24/7 preventative approach to incident management. 

Disaster Recovery

A Disaster Recovery plan is one of the most important yet least prioritized documents. It should outline the procedures needed to restore services after a disaster event. The document should cover at least the following items:

• Scope
• Steps to restore service as soon as possible
• How to determine damage or data loss, risk assessment
• Emergency response — who should be notified and how?
• Steps to back up all data and services

The main goal of a Disaster Recovery plan is to ensure that business operations continue, even after a disaster. Failure to recover presents a large gap in the infrastructure. 

Best Practices You Should Follow

Formatting

When creating documentation, it is important to follow certain rules. Let's identify them:

1. Organization: A stable company will usually have a brand book that establishes boundaries and provides guidelines for content. In the case of documentation, you may need to use a specific font, size, and layout, and you may be required to include a logo or other elements. Before documenting,  find out what the company requirements are. If there are no established guidelines, create your own to establish consistency across your department.

2. Grammar: The way you communicate while documenting should also follow a standard. Some best practices include:

   • Use an active voice, i.e., The entire infrastructure is described as code via terraform. 

   • Avoid a passive voice, i.e.: Terraform was used to describe the entire infrastructure as code. 

   • Avoid long sentences. Stick with simple structured sentences that are easy for the reader to follow.

   • Create a glossary of abbreviations, and use consistent terminology. For example, if you mention an SSL certificate but you use TLS instead, the reader might be confused.

   • Use appropriate verb tenses: For example, use the present tense for describing a procedure and the past tense for describing a completed action.

3. Storage: When saving the document, always use a conventional name that makes it easy to find and share with others. Store the file in the most appropriate path or structure, such as a particular file system or a collaborative tool like Confluence. 

File naming example: 

departmentname_typeofdocument_nameofdocument_mm_yyyy 

ManagedServices_internal_stepsfordocumentation_03_2023

Content

How you display your document’s content plays a relevant role in the entire process. A document that is attractively laid out and easy to read will help to prevent confusion and avoid unnecessary questions. 

Here are some tips for you:

1. Screenshots: A picture is worth a thousand words. Use screenshots to help the user better relate to your instructions.

Within your AWS Account, go to the EC2 Dashboard and check the Security groups. 

2. Diagrams: A flow chart provides a visual aid to help you describe a step-by-step process so that the reader can easily identify which step they are on.  

1. Open the console

2. Ping the corresponding IP

3. If you get an error, copy and paste the message

4. Open ticket in AnyDesk 

5. Paste the error message

6. Assign to AnyTeam

3. Table of contents: Use heading formats to create a table of contents. If the document is quite large, the reader will have the option to jump to a specific section. That reader could be you, wanting to update the document a few months later!

4. Troubleshooting: Readers will likely have some issues when putting your document into action. Be sure to include a troubleshooting section to help resolve common problems. 

Lifecycle

One of the most common mistakes in documenting is to think documentation is over because the project is up and running. Keeping your documentation  up to date is an important part of the documentation lifecycle:

1. Maintenance: Considering that your Infrastructure is constantly changing, your documentation must be kept current. Outdated documentation will misinform others and could trigger disastrous actions. 

2. Back-up: Always keep a backup of your documents. Ideally, your place of storage should have certain features by default, like versioning control, searching, filtering, collaboration, etc. But it is also a good practice to keep your own backup – it might be useful one day.

3. Share: Once you have completed documentation, share it with potential users and ask for feedback. They can help suggest improvements that make your documentation more robust.

Conclusion

If you are not 100% convinced about the benefits of documentation, think of it this way: No one wants to waste time figuring out someone else’s work or reinventing the wheel by creating a project that has already grown and evolved. Documentation that is clear, concise, and easy to understand is the first step toward building a successful cloud infrastructure.