FUBAR: Techies and Documentation

We all know this picture, right? Especially that auspicious void in "How the Project was documented" makes most of us chuckle and realize we have seen this happen more often than we would want to. Most of the colleagues and customers I have worked with until now, with a few exceptions, are really bad at documenting things they build or change. Be it a new deployment of an infrastructure, a recipe for an application package, thinapp or a new random server, the information often remains in the mind of the person, instead of on "paper". 

Now why is this? Is it because we do not see the value of writing down exactly what we did, is it simply forgotten, or do we not take an acceptable amount of time for it to be written. Is it not in the budget? Not in the project planning? WHY????

I did a small poll on twitter and asked for the why: Why are you not documenting your project, change or other IT related stuff... The outcome was pretty shocking, more than half the people answered: I'm too lazy! The other choices were I don't have the time and I don't see the use, which were hardly used. It is a bit shocking to see, but then again, most IT personnel love doing IT, but not writing stuff down. Conclusion must be, IT people don't like documenting...

We all know this picture, right? Especially that auspicious void in "How the Project was documented" makes most of us chuckle and realize we have seen this happen more often than we would want to. Most of the colleagues and customers I have worked with until now, with a few exceptions, are really bad at documenting things they build or change. Be it a new deployment of an infrastructure, a recipe for an application package, thinapp or a new random server, the information often remains in the mind of the person, instead of on "paper". 

Now why is this? Is it because we do not see the value of writing down exactly what we did, is it simply forgotten, or do we not take an acceptable amount of time for it to be written. Is it not in the budget? Not in the project planning? WHY????

I did a small poll on twitter and asked for the why: Why are you not documenting your project, change or other IT related stuff... The outcome was pretty shocking, more than half the people answered: I'm too lazy! The other choices were I don't have the time and I don't see the use, which were hardly used. It is a bit shocking to see, but then again, most IT personnel love doing IT, but not writing stuff down. Conclusion must be, IT people don't like documenting...

Why Should You Document?

• The transfer of knowledge: Documentation ensures that the knowledge of how a system was built or modified isn’t lost when someone leaves the team or company.

• Communication of knowledge: Clear documentation helps team members, stakeholders, or future IT staff understand what was done and why, fostering better collaboration.

• It will save you time: Well-documented systems mean less time spent reverse-engineering or troubleshooting issues because the information is readily available.

• The right people get the right information: Documentation ensures that critical details reach the appropriate team members, reducing miscommunication and errors.

• Things won’t be forgotten or lost: Systems evolve, and human memory fades. Written records preserve the context and specifics for future reference.

When you are creating something as part of a change or a project, it can be really valuable to document both the design and the installation. It has advantages when you can easily find those detailed settings, a design decision, a name of a server, a connection between systems, or anything else you need when either troubleshooting or, for example, doing an upgrade of an existing system. Including either a reference to a ticket log system or at least a description of why a change was made can prevent hours of guesswork later.

How Do You Create Documentation?

Try to make it so that there’s as little room as possible for interpretation. This is one of the hardest things to do. Ambiguity in documentation can lead to confusion, errors, or even system failures. Here are some practical tips to create clear, effective documentation:

Installation Documentation

• Screenshots: Visuals are incredibly helpful. Include screenshots of configuration screens, settings, or terminal outputs to provide a clear reference. Annotate them if needed to highlight key details.

• Clear Steps: Write step-by-step instructions as if guiding someone with minimal context. Use numbered lists or bullet points for clarity. For example, instead of saying “configure the server,” specify “Log into the server via SSH using ssh admin@192.168.1.100, then run sudo apt-get update.”

• Standardize: Use templates or standardized formats for documentation across projects. This ensures consistency and makes it easier for others to find information quickly. For example, include sections like Purpose, Prerequisites, Steps, and Post-Installation Checks in every document.

Design Documentation

• Explain the Why: Document the reasoning behind design decisions. Why was a particular technology chosen? What trade-offs were considered? This helps future teams understand the context.

• Diagrams: Use tools like Visio, Lucidchart, or even simple sketching tools to create network diagrams, architecture overviews, or data flow charts. A picture is worth a thousand words.

• Version Control: If your documentation evolves, use version control (e.g., Git for text-based docs) to track changes and ensure everyone is working with the latest information.

Where Can You Put This Knowledge?

Storing documentation in an accessible, organized way is just as important as creating it. Here are some common places to store IT documentation:

• Fileshare: A shared drive (e.g., Google Drive, OneDrive) is a simple option, but ensure proper access controls and folder organization to avoid chaos.

• Microsoft Teams: Teams can be a great hub for collaborative documentation. Use channels for specific projects and pin important documents for easy access.

• Knowledge Base: Tools like Confluence, Notion, or a company wiki provide a structured, searchable way to store documentation. They’re ideal for long-term knowledge retention.

• Incident Registration System: For changes tied to specific incidents or tickets, link documentation to the relevant ticket in systems like Jira or ServiceNow. This keeps everything traceable.

Automating Documentation with Tools like AsBuiltReport

Manual documentation can be tedious, but automation can significantly reduce the effort while improving consistency and accuracy. One powerful tool for IT documentation is AsBuiltReport, an open-source PowerShell-based framework that generates as-built documentation for various datacenter technologies, including VMware vSphere, Omnissa Horizon, Microsoft Active Directory, Veeam, and more.

Why Use AsBuiltReport?

AsBuiltReport automates the process of collecting configuration details from your IT environment and presenting them in professional, customizable formats like DOCX, HTML, or Text. Here’s how it can help:

• Efficiency: Instead of manually collecting data, AsBuiltReport uses PowerShell scripts to extract information directly from systems via PowerShell or RESTful APIs, saving hours of work.

• Consistency: The tool uses a modular architecture with predefined templates, ensuring uniform documentation across different technologies and vendors. You can customize styles to match your corporate branding, including fonts, colors, and layouts.

• Granular Control: You can configure the level of detail in each report section, from high-level summaries to comprehensive configuration details. Health checks can be enabled to highlight potential issues in your environment.

• Ease of Use: With commands like New-AsBuiltReport, you can generate reports by specifying a target system, credentials, and output format. JSON configuration files store settings like author details or SMTP configurations for easy reuse.

Getting Started with AsBuiltReport

To use AsBuiltReport, you’ll need PowerShell 5.1 or PowerShell 7 and the PScribo module for formatting. Installation is straightforward via the PowerShell Gallery:

Install-Module -Name AsBuiltReport.Core -Repository PSGallery -Scope CurrentUser

You can then install specific report modules (e.g., AsBuiltReport.VMware.vSphere or AsBuiltReport.Microsoft.AD) for your environment. Create a JSON configuration file using New-AsBuiltConfig to store non-technical details like author or company information, and use New-AsBuiltReport to generate reports. For example:

New-AsBuiltReport -Report VMware.vSphere -Target 'vcenter-01.corp.local' -Username 'administrator@vsphere.local' -Password 'VMware1!' -Format Html,Word -OutputFolderPath 'C:\Users\Tim\Documents' -EnableHealthCheck

This command generates a VMware vSphere report in HTML and Word formats, with health checks enabled, and saves it to the specified folder.

Benefits of Automation

By automating documentation with tools like AsBuiltReport, you address the “too lazy” problem head-on. The process becomes faster, less error-prone, and produces professional-grade output that can be shared with clients or teams without additional tweaking. Automation also ensures documentation stays up-to-date, as reports can be scheduled to run regularly, combating configuration drift.

For more details, visit the AsBuiltReport website (https://www.asbuiltreport.com) or check out their GitHub repositories for specific modules and documentation.

Making Documentation a Habit

To overcome the “laziness” factor from the Twitter poll, integrate documentation into your workflow. Here are a few strategies:

• Document as You Go: Instead of leaving it for the end, take notes during the process. Tools like OneNote or a simple text editor can help capture details in real-time.

• Allocate Time: Treat documentation as a project deliverable. Include it in your project timelines and budgets to ensure it’s not an afterthought.

• Automate Where Possible: Use tools like AsBuiltReport to generate detailed, professional documentation with minimal effort. Automation reduces the time and mental overhead of manual documentation.

• Peer Reviews: Have a colleague review your documentation for clarity and completeness. This can catch gaps and improve quality.

• Make It Rewarding: Celebrate well-documented projects or recognize team members who excel at it. Positive reinforcement can shift the culture.

Final Thoughts

Documentation isn’t the most glamorous part of IT, but it’s a game-changer for efficiency, collaboration, and long-term success.

By making it clear, consistent, and accessible (whether through manual effort or automation tools like AsBuiltReport) you’re not just helping your future self, you’re empowering your team and ensuring your systems run smoothly. Automation takes this to the next level by removing the tedious manual work, making it easier to produce professional, up-to-date documentation without breaking a sweat. So next time you’re tempted to skip documentation because you’re “too lazy,” remember: a little effort now, or a smart automation tool, can save hours (or even days) of headaches later.

Let’s break the cycle of that empty “How the Project was Documented” section and make documentation a habit worth keeping—preferably with a bit of PowerShell magic to make it painless.

What’s your take? How do you tackle documentation in your IT projects? Have you tried automation tools like AsBuiltReport? Let me know!