You’ve probably been there before: Ready to dive into a new project with a vision for the improvements you’ll make and all the problems in the code you’ll fix once and for all. 

As you work, you come across code that doesn’t make sense. You ask around: “What’s this code for? What a waste! Does anyone know more about this code?” Your questions are met with blank stares and crickets, so you decide to rip that code out.

With your perfected feature ready to go and all past problems removed, you ship to production. But things don’t go as planned.

Your changes suddenly blow away subtle edge cases that other teams had accounted for. Or maybe your updates fixed a bug another team relied on, shutting down another service. If only there had been documentation around the code you removed!

The success of today’s engineering projects depends on good documentation. When future co-workers, direct reports, or even you go to pick up a project, understanding past decisions and tradeoffs made can save headaches and heartbreaks. 

Here’s the problem: Although most developers indicate they’d like more documentation as they take on new projects, they’re reluctant to create it. Why? It’s hard to know where the documentation should live, what format it should take, and how it should be accessed. Plus, creating documentation can feel like it’s in the way of writing more code, prompting developers to skip over this important task.

At Lucid, we’ve turned to our products to help our developers effortlessly create, maintain, and store documentation. Here’s how our engineering team has transformed documentation from a complicated chore into a natural part of our workflow.

The benefits of using Lucid for documentation

No matter how much effort we put into our documentation, we still found ourselves wanting something better. Before we used our products, it was hard to find the connections between projects. Documentation often took many different forms as different departments used different tools. We needed a standard way to create and centralize all project info.

We turned to the Lucid Suite to bring together all documentation for projects, such as Figma mocks, solutioning, estimation, alignment meetings, Jira issues, and confluence documentation. 

Using Lucid has helped us align by:

• Keeping our developers on the same page throughout a project. 

• Consolidating the different tools and associated artifacts into one place.

• Bringing others up to speed when they joined the project.

We no longer have to guess what sections of code are for—we can find all that information easily within Lucid.

How our engineers streamline project documentation with Lucid

Because Lucid combines intelligent diagramming through Lucidchart with virtual whiteboarding through Lucidspark, our engineering team can use Lucid throughout the entire development cycle. And the more we use Lucid to work, the more documentation we create. 

Here are some of the most valuable ways we use Lucid to create and store documentation:

We create custom templates to standardize processes

First, we create and share a custom Lucidspark template for teams to fill out as they take on new projects (try out the template). This template helps ensure junior team members consider all the complexities of a project, such as business value, target audience, customer impact, and the release team on the project. 

We also use this documentation to set expectations that there should be an architecture review and specific tracking to make the project successful. We can loop in designers and product owners to help flesh out requirements and keep everything shared in one place. Different teams can easily leave comments and tag teammates with questions as they work together to complete the project brief.

We embed links to bring together documents created in different tools

Within the template, we can embed links to external sources from which we’ve created documentation. Typically, these include Lucidspark brainstorming sessions, Lucidspark project timelines, Lucidchart architecture diagrams, Figma designs, Confluence pages, or even links to code in our repository. 

By adding in all related project documentation to this shared Lucidspark board, we create a single source of truth that anyone involved in the project can reference. Our team no longer has to waste time searching across different tools to find information.

We use integrations to visualize progress

Lucid’s integrations have completely transformed our workflow, and the Jira integration is one of our team’s favorites. Using Lucid’s integration with Jira, we can import all tasks related to a project directly in Lucid as Lucid Cards. By bringing these tasks together with other project documentation, we can easily see if the team is staying on track to complete the project on time. 

Anytime a task is updated in Jira, it’s also automatically updated in the Lucidspark document—and vice versa. This bi-directional sync means that whenever we want to make updates as we review, we can do so directly from Lucidspark, knowing those changes will be reflected in Jira. We move so much faster now that we don’t have to manually update multiple sources.

We align with stakeholders asynchronously 

How do we get people to use these documents? We conduct weekly asynchronous reviews of teams and their projects. 

Each team pulls together the latest information from different projects and puts it all in one place. With this information centralized, it’s easy for me, as a director, to review projects and dive deeper into the details if I’m interested or have more questions. 

I can @mention others in the document and leave sticky notes to provide my team with direction and opportunities to clarify the work. Asynchronous reviews also keep teams accountable for managing the project documentation since they know leadership frequently references these documents to learn more.

The visual documentation helps all stakeholders get on the same page way faster than trying to do this via Slack or verbally in meetings. All the context is in one spot, and it’s easy to see the relationship between ideas, comments, feedback, and more.

We centralize project info in our team hub and team space

To further help organize our documentation and coordinate work, we use our team hub in Lucid. Our team hub allows us to keep all of our Lucid content together in one place and make it accessible to the entire team. This additional layer of organization makes it incredibly easy to find previous project briefs we need to reference as we work on new projects.

With all documentation centralized across different projects, we’ve taken the guesswork out of decision-making. Our engineers can see a record of decisions made without having to track down who was on each project. We can now make more confident decisions about what to keep or remove in the code.

In the team hub, we’ve pinned our team space, which includes references and links to all of our project briefs and updates. Since we can see the high-level progress of all projects and what teams are focused on right now, it’s easy to stay on track.

By using Lucid for documentation, we now have better-aligned teams that can more easily bring in new engineers on projects—whether it’s the same project we’ve been working on for a few months or one we wrapped up two years ago. Having a central place to go back and see what decisions were made before us helps us all avoid unintentional mistakes and keeps our systems running smoothly.