DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Last call! Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Explore Azure Documenter, One of the Efficient Azure Documentation Generator Tool With Useful Features
  • Elasticsearch Query and Indexing Architecture
  • How Jenkins Can Stay Relevant in the Next Decade
  • Design Principles-Building a Secure Cloud Architecture

Trending

  • MySQL to PostgreSQL Database Migration: A Practical Case Study
  • Integration Isn’t a Task — It’s an Architectural Discipline
  • Beyond ChatGPT, AI Reasoning 2.0: Engineering AI Models With Human-Like Reasoning
  • Why High-Performance AI/ML Is Essential in Modern Cybersecurity
  1. DZone
  2. Software Design and Architecture
  3. Cloud Architecture
  4. Documentation 101: How to Properly Document Your Cloud Infrastructure Project

Documentation 101: How to Properly Document Your Cloud Infrastructure Project

In this article, I will help you to understand the importance of documentation and offer some easy steps for implementing best practices.

By 
Carolina Chavarria user avatar
Carolina Chavarria
·
Mar. 28, 23 · Tutorial
Likes (7)
Comment
Save
Tweet
Share
8.0K Views

Join the DZone community and get the full member experience.

Join For Free

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. 

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

  1. 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

Flow chart diagram


  1. 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!

  2. 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.

Diagram Document Documentation Cloud Architecture

Opinions expressed by DZone contributors are their own.

Related

  • Explore Azure Documenter, One of the Efficient Azure Documentation Generator Tool With Useful Features
  • Elasticsearch Query and Indexing Architecture
  • How Jenkins Can Stay Relevant in the Next Decade
  • Design Principles-Building a Secure Cloud Architecture

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!