Rethinking Documentation. A Technical Writer's Journey into the Atlassian Ecosystem

[#1]

Hi, I'm Evelin – a technical writer and UX writer.

I'm new to the Atlassian ecosystem, so you can think of this as my introduction post. At the same time, I'd like to share a few first observations from a technical writer's perspective—and connect with others in the community who help people find, understand, and share knowledge, whether they consider themselves writers or not.

The beginning

When I joined codefortynine, a Marketplace app vendor, a few weeks ago and entered the Atlassian ecosystem, I expected to learn a new set of tools.

After all, I'd been using Confluence and Jira as an end user for years. But now I'd switched to the perspective of a Marketplace app vendor—and, for the first time, I was using Confluence together with Scroll Sites as an authoring tool for professional technical documentation.

There was a lot I expected: learning a new product world, shifting from an end-user to a vendor perspective, and adapting to new documentation tools and workflows after years in other industries.

What I didn't expect was discovering an entirely different culture of documentation.

Where I come from

I've spent many years working in what I would call a traditional technical documentation environment:

• Structured authoring

• Advanced content reuse

• Git-based workflows

• Content analysis (broken links, missing references, excluded content)

• A strong focus on consistency and traceability

So when I started creating documentation in Confluence, my first instinct was to look for familiar concepts.

• How do I reuse content?

• How do I structure information?

• How do I keep documentation changes traceable?

Some answers were easy to find. Others weren't. And yes—there are still features I genuinely miss from my previous documentation environment.

One example is traceability. In my previous workflow, documentation commits from my authoring tool were linked directly to Jira issues. It was immediately obvious what had changed, why it had changed, and which task it belonged to. Confluence offers a different model. Its page history feature is certainly useful—but it answers different questions.

At first, all I saw were missing features...

My mindset shift

After a few weeks, I started wondering if I still hadn’t fully understood what Confluence is all about.

Confluence can be used as a technical authoring tool. But the heart of Confluence—and of the Atlassian ecosystem as a whole—is collaboration. And collaboration means that knowledge is created by many different people, each bringing their own perspective, terminology, writing style, and way of organizing information.

As technical writers, we're trained to reduce variation. We define templates, information models, writing guidelines, and content structures to create documentation that is as consistent as possible.

Collaboration starts from a different premise.

It isn't built around perfect consistency. It's built around enabling many people to contribute.

Developers, product managers, support engineers, consultants, marketers, and technical writers all contribute to documentation.

Confluence doesn't try to eliminate the diversity of how people think, write, and share knowledge.

Instead, it embraces that diversity and focuses on making knowledge discoverable.

A different question

And more than that: one thing that surprised me was how distributed knowledge is in the Atlassian ecosystem. Documentation is only one part of a much larger knowledge landscape.

Helpful information lives in Confluence pages, Jira work items, Community articles, Loom videos, comments, Marketplace documentation, and countless conversations.

That changes the question I'm asking. Instead of spending all my energy on:

"How do I structure this information perfectly?"

I increasingly find myself asking:

"How will people find this knowledge?"

Maybe that's the more relevant question in a collaborative ecosystem.

Finding knowledge isn't just about well-written documentation. It's about making information discoverable—through good structure, search, links, community discussions, cross-references—and, inevitably, AI.

None of this replaces good documentation. These are different ways of making knowledge discoverable.

I'm still very much at the beginning of this journey. These are my first observations from someone who's only just beginning to understand the Atlassian ecosystem.

I'm curious to hear how others think about documentation and knowledge sharing.

Have you worked with traditional help authoring tools and structured authoring? Or has collaboration always been your starting point? Has your perspective changed over time—and if so, in what way?

I'd love to hear your thoughts.

[Elena_Elevatic]

Welcome to the ecosystem, @Evelin Bayer - codefortynine 

Great first post!

Coming from copywriting before product marketing, your "how will people find this knowledge?" shift really resonated. Copywriters obsess over the reader's context—where they are, what they already know—so it's less about perfect structure and more about meeting people where they actually are.

One thought: consistency and discoverability aren't really opposites. Consistent terminology is often what makes things findable later, especially now that search and AI do so much of the surfacing. Maybe the collaborative model doesn't kill the structured-authoring instinct—it just changes where you apply it: less locking down every page, more on the connective tissue that ties scattered knowledge together.

Following along on the journey! :)

[Evelin Bayer - codefortynine]

Hi @Elena_Elevatic ,

Thanks for joining the discussion and for adding a copywriter's perspective! I always enjoy exchanging ideas with writers from different backgrounds.

Meeting people where they actually are.

Love that phrase. And you're right—that's really at the heart of technical writing, too. It's just one of those things that's easy to lose sight of in day-to-day work, so it's always worth reminding ourselves.

And I think you're absolutely right about consistency and discoverability. They're not opposites, they reinforce each other.

Maybe the real shift isn't that structured authoring principles become less important in a collaborative environment. Maybe it's that they move to a different level. Less about making every single page look and read exactly the same, and more about information architecture, metadata, links, searchability, and helping people find the right knowledge.

Thanks for sharing your perspective!

I'll definitely keep thinking about it as I continue learning my way through the Atlassian ecosystem.

[Brita Moorus]

Welcome, @Evelin Bayer - codefortynine! 💙

[Kris Klima _K15t_]

Hello @Evelin Bayer - codefortynine 

A fellow tech writer here :) This really resonates!
(Although I'm not practicing the trade actively at the moment.)

You recounted an interesting journey, a total opposite of what I experienced. I jumped into Confluence early on... documenting mainframe software. 

Back then, CA Technologies were migrating their entire documentation archive from AIT (XML-based) to Confluence. Which was unheard of. We're talking hundreds of thousands of pages (if not millions) of products with 50 years of continuos development.

Handling that scale and complexity in Confluence was so much easier - especially when we added advanced features like versioning and translations. Everything sped up. Massively. Updating documentation with pretty much zero dependencies was a revelation. I remember customers astonished when we showed them we can fix typos or add new details in real time.

And you're absolutely right... Collaboration. In the world of mainframes, writers must rely on developers for drafts and general knowledge. And they loved being able to work in the same environment as we did. Especially extending the WYSIWYG principle from text editor to Structure. They could draft and edit always in the context of other pages.

This was amazing - everybody from the team could be on the same page (any page), at any time, and at any stage of the life cycle.

This team-wide convergence lead to CA pioneering the concept of DocOps. Approaching documentation as any other asset, making it a part of the product, but without forcing writers to use tools designed to write code :) 

The sync between docs and devs happens via Jira. Which is another reason to love Confluence, especially in its modern Cloud iteration. I learned to treat Confluence and Jira as a single tool.

I flirted with doc-as-code and other tools but, frankly, I found the experience lacking and inferior to Confluence. From re-basing, dependencies, DIY solutions, writer isolation... 

Is it a universal best tool? No. But it's so pliable and expandable with apps that it's pretty universal.

I summarize my thoughts in a blog post Why Use Confluence for Documentation and a guide on how to choose a documentation tool which, if you read it carefully, makes it really hard not to choose Confluence :) 

Feel free to get in touch for tips and tricks on Confluence terraforming :)