New to Confluence? One Tip to Make Your Developers Love Your Documentation
Hi everyone, and welcome to the Confluence community!
If you're new here, you're probably excited about setting up your first few spaces and turning Confluence into your team's single source of truth. It's a powerful tool, and establishing good habits early on can save you and your team countless hours down the road.
Today, I want to share one simple tip for writing product documentation that will prevent a major headache and make your engineering team incredibly happy.
The Common Mistake We All Make at First
When we start documenting a new feature, our first instinct is to write everything in paragraphs, like this:
"...the page will have a title that says 'Welcome to Your Dashboard'. Below the title, we need a paragraph of text that reads 'Here you can see a summary of your recent activity.'. There should also be a button on the right that is labeled 'View Full Report'..."
This seems logical, right? But after a few months, this becomes a problem:
- It's hard to find: When you need to update a button label, where was it mentioned? You have to search through pages of text.
- It gets out of date: The text in the documentation and the text in the actual app quickly fall out of sync.
- It creates work: A developer has to read your entire paragraph, find the text, and then manually copy it into the code.
A Better Way: Treat Your App's Text Like Data
Here's the pro-tip: separate your user-facing content from your descriptive documentation.
A simple way to start is by creating a table on your Confluence page for all the text that will actually appear in your app's user interface (UI).
| Element Name | Text to Display |
dashboard.title | Welcome to Your Dashboard |
dashboard.summary | Here you can see a summary of your recent activity. |
dashboard.report_button | View Full Report |
[Example of an application comment]
By organizing your content this way, it’s always clean, easy to find, and ready for a developer to use.
Making This Best Practice Effortless
We loved this approach so much that we decided to automate it. We built a simple app called Quick Locale AI (QLAI) that does the hard work for you.
You can still write your documentation naturally, and our app's AI will:
- Read your page and automatically identify any text meant for the user interface.
- Create a clean, organized table like the one above for you.
- Even translate the text into other languages if you need it.
- Sync it all so your developers have instant access to the most up-to-date content.
Starting with an organized workflow from day one will make your life easier as your product grows. You'll have documentation that is always up-to-date, and your developers will thank you for it.
Happy documenting!
If you're interested in trying this automated approach, you can check out Quick Locale AI on the Atlassian Marketplace.