5 ways engineering teams can streamline project documentation with Lucid

Andy Hurd

Reading time: about 6 min

Topics:

  • Product development
  • Lucid updates
  • Expert tips

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 engineer’s toolkit for effortless documentation

Kick-start any project with templates for everything from creating product roadmaps to designing technical systems.

Get the toolkit

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.

Click on the template image to create your own project documentation.
Click on the template image to create your own project documentation.

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.

Embed links directly into the doc to centralize all key project information.
Embed links directly into the doc to centralize all key project 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.

Lucid’s two-way sync with Jira helps teams stay aligned, even as plans change.
Lucid’s two-way sync with Jira helps teams stay aligned, even as plans change.

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.

In Lucid, it’s easy to collaborate in real time or asynchronously.
In Lucid, it’s easy to collaborate in real time or asynchronously.

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.

Create a team hub in Lucid to bring project documentation from various projects together under one roof. Click on the image to learn more.
Create a team hub in Lucid to bring project documentation from various projects together under one roof. Click on the image to learn more.

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.

Use team spaces to coordinate your team’s work. Include timelines, updates, and all other communication in your team space.
Use team spaces to coordinate your team’s work. Include timelines, updates, and all other communication in your team space.

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.

Get your engineering team on Lucid

Contact us to see how your engineering team can use Lucid to document everything from feature brainstorms to complex architecture in one shared space.

Request a demo

About the author

Andy Hurd, a senior director of engineering at Lucid, has been with the company for a whopping 10 years. He enjoys solving challenging problems, including employee growth and technical problems. In his home life, he enjoys traveling with his spouse and two kids.

About Lucid

Lucid Software is a pioneer and leader in visual collaboration dedicated to helping teams build the future. With its products—Lucidchart, Lucidspark, and Lucidscale—teams are supported from ideation to execution and are empowered to align around a shared vision, clarify complexity, and collaborate visually, no matter where they are. Lucid is proud to serve top businesses around the world, including customers such as Google, GE, and NBC Universal, and 99% of the Fortune 500. Lucid partners with industry leaders, including Google, Atlassian, and Microsoft. Since its founding, Lucid has received numerous awards for its products, business, and workplace culture. For more information, visit lucid.co.

Related articles

  • The engineer’s toolkit for effortless documentation

    To get you started with collaborating visually and documenting as you go, we’ve compiled a toolkit of templates for common engineering use cases. 

  • How Lucid engineers use Lucid to collaborate across the entire software development lifecycle

    Learn how Lucid’s engineering teams use Lucid to collaborate better, solve problems quickly, and innovate continuously.

  • 3 ways Lucid accelerates innovation for R&D teams

    R&D teams need ways to innovate faster, and Lucid’s visual collaboration is the solution. Learn more here.

  • What makes Lucid the most intelligent visual collaboration platform—and why does it matter?

    From data-backed visualizations to automation and AI, find out what makes Lucid the most intelligent visual collaboration platform.

Bring your bright ideas to life.

Sign up free

or continue with

Sign in with GoogleSign inSign in with MicrosoftSign inSign in with SlackSign in

By registering, you agree to our Terms of Service and you acknowledge that you have read and understand our Privacy Policy.

Get Started

  • Contact Sales

Products

  • Lucidspark
  • Lucidchart
  • Lucidscale
PrivacyLegalCookie privacy choicesCookie policy

© 2024 Lucid Software Inc.