.svg){kind=logo}
Internal product documentation helps employees build, test, maintain, support, market, and sell your apps.
According to the 2023 Onboarding Survey by Glean and OnePoll, 77% of workers believe that access to information without having to ask for it empowers them and improves their productivity. So, by giving employees easy-to-understand instructions about your apps, you’re helping them get up to speed quicker, reducing onboarding time.
Visuals are vital to making those instructions easy to understand. Since text can be misinterpreted, visuals confirm how your product works.
The thing is, the go-to method for demonstrating an app is screenshots. And instructions with screenshots are a pain in the ass to create and maintain.
If you’re using Confluence for technical documentation for internal teams, there’s an alternative to screenshots that can save you a bunch of time and improve the quality of your visuals at the same time. Figma links.
Let’s explore how.
Screenshots aren’t the most effective way of explaining your products, how they work, and what their use cases are for 3 main reasons.
An employee might need to enlarge an image to better understand how your app works. But screenshots are raster images, which become blurry and pixelated when you resize or zoom in on them. Ideally you want your visuals to be vector graphics, which scale cleanly at any resolution.
Taking screenshots is a very manual and labor-intensive process. You have to open the screen, position it, pull up your screenshot tool, take the shot, crop it, save it, and upload it to your Confluence page. Rinse and repeat for every screen.
Instructions with screenshots carry a massive maintenance overhead. Screenshots are static images that capture a moment in time, so the second your product’s user interface (UI) changes, they become outdated.
If screenshots aren’t maintained, they’ll mislead or confuse the stakeholders working on your apps. But replacing outdated screenshots isn’t quick or easy. It involves creating, editing, and saving a new screenshot from scratch, deleting the old one, uploading the new one, and sometimes, manually replacing the old one in multiple places.
This can become arduous and very time-consuming, especially in agile environments where UIs change frequently. One tiny UI adjustment can sometimes snowball into dozens of screenshots needing to be updated.
And, of course, every screenshot is a new file you have to store somewhere, cluttering up your system.
The other thing is that screenshots don’t signal when they’re stale. Someone would need to audit them manually on a regular basis. If that doesn’t happen, the only way you’d know is if a stakeholder reports an issue. It’s why outdated images in product documentation can sit unnoticed for months or years.
A Figma link is a live link to a design in Figma, which you embed into a Confluence page. It means that when the UI changes in Figma, those changes can be reflected easily or even automatically in Confluence, depending on the tool you use.
The maintenance overhead is dramatically reduced because you don’t have to create, edit, save, and re-upload. Far fewer actions are required, and there’s no image management because you’re not creating new files.
Better still, Figma embeds render on the page like vector graphics, which allows users to zoom in as much as they like without losing clarity.
If you use the free Figma Live Embeds feature to add Figma frames to your Confluence technical documentation, there are two problems you’ll likely run into.
With Figma Live Embeds, you’ll always see the latest version of the frame when you open the Confluence page.
In other words, as soon as your UI changes in Figma, the embedded file will update in Confluence, too.
This seems great compared to making and adding new screenshots every time. It means the visuals in your internal product documentation stay up to date automatically.
There’s a big BUT. Redesigning a UI is an iterative process. Designers will move, tweak, and test things before settling on a final design. So, live embedding means your documentation could show work-in-progress UIs. Even when the design is finalized, it still needs to be implemented. With live embeds, your documentation will change before your product does.
Seeing a different UI from the actual product could cause managers to misjudge progress, quality assurers (QA) to write incorrect test cases, and marketers to promote features before they’re ready.
Here’s where screenshots have a major advantage over Figma links. No one needs an expensive license to view a screenshot. But with Figma Live Embeds, users will only be able to see private Figma designs in Confluence if they log in with a Figma account.
Most of your employees won’t be designers who need to use Figma, and no company is going to justify buying licenses for everyone just so they can view their internal documentation. They’ll go back to making instructions with screenshots.
When you embed a Figma design into a Confluence page with Figma for Confluence Pro, you avoid both problems: buying licenses for non-Figma users, and your visuals changing before you’re ready.
Figma for Confluence Pro has a unique authentication feature that lets Confluence users access private Figma designs in Confluence without a Figma license.
In big companies especially, this is much cheaper than buying Figma licenses for employees who need to see Figma designs to understand and work on your apps, but don’t otherwise have any use for Figma.
Ideally you want a middle ground between a static screenshot that has no connection to the source file and needs remaking every time, and a live embed that changes automatically, even when you don’t want it to.
That middle ground is version control. When you add a Figma design to a Confluence page with Figma for Confluence Pro, that version of the design gets pinned to the page. Any changes made after embedding the file won’t automatically propagate to Confluence. It means that when you redesign your UI, the changes won’t reflect in your internal product documentation until you’re ready.
When you are ready, instead of the many steps involved in replacing a screenshot, just click into the Figma embed and update the version. Updating the visuals in your documentation isn’t automatic, but it’s far less manual effort than screenshots. And by not letting a work-in-progress or future UI display in your pages, you preserve their integrity.
.png)
Figma for Confluence Pro also helps with maintenance in another way. We said earlier that screenshots don’t tell you when they’re outdated. But Figma embeds made with Figma for Confluence Pro do.
When a design gets updated in Figma, a small icon of 3 stars will appear in the top right of the embedded panel in Confluence. (If you’re using the frameless view, the 3 stars will appear when you hover over the design.) When you hover over the 3 stars, it will say, “A new version is available.”
.png)
This alerts the person responsible for maintaining your Confluence technical documentation that the embed needs to be updated.
Instructions with screenshots are old hat. Companies are still doing them because they’ve always done them, and they don’t know there’s a better, quicker way.
Obviously, Figma Live Embeds comes with a huge disadvantage: everyone needs a Figma license. This makes screenshots a lot cheaper. Unless, of course, your whole company is using Figma day to day.
Then there’s the fact that Figma’s free embeds are always live. The main problem with screenshots is that they get outdated quickly, but Figma’s free embeds do the opposite. If the UI changes in Figma before going live in the app, then your Confluence product documentation will show work-in-progress or future versions of your UI.
None of this is helpful to internal stakeholders managing, developing, and selling your product.
But Figma for Confluence Pro solves these problems. You can have Figma links on Confluence pages that any Confluence user will be able to view, inspect, and download without logging in to Figma. And the danger of them seeing the wrong UI is dramatically reduced by the version control feature.
If you want to move beyond creating instructions with screenshots to something more efficient, maintainable, and scalable, try Figma for Confluence Pro free for one month.
A former lawyer, Berry loves theme parks, has published a sci-fi conspiracy thriller trilogy called Million Eyes to rave reviews, and is a specialist in writing content for tech companies.
