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 :) 

[Evelin Bayer - codefortynine]

Thanks, @Brita Moorus 🙏

[Evelin Bayer - codefortynine]

Hi @Kris Klima _K15t_ ,

Thanks for your input and for sharing the links! It's great to hear from someone who's been in the game much longer than I have.

Especially your article Why Use Confluence for Documentation (including all your Marketplace recommendations for technical writers) definitely gave me plenty to dig into.

I completely agree with your point about the trade-off between collaboration and specialized authoring tools. My previous setup was MadCap Flare, Git, Bitbucket, and Jira. It gave me incredibly powerful capabilities for structured authoring, reuse, conditional content, content analysis, and traceability. But it was much more of an isolated technical writing environment. Getting developers, PMs, SMEs, QA engineers, or designers to contribute directly in the same tool? No way.

So I don't question that Confluence is much better at bringing everyone together. In fact, that's one of the things I'm most excited about—the collaborative spirit across the entire ecosystem.

That said, I don't want it to be a trade-off between collaboration and governance or traceability. I'm not willing to compromise just yet :D

So I guess, over the next weeks and months, I'll be spending some more time looking for good solutions around:

• nesting of macros
• reusable content and its traceability
• conditional content
• avoiding broken links when pages are archived or excluded

I'm genuinely curious how others have solved challenges like these in practice.

One thing I'm still trying to understand is how you addressed governance and traceability at CA. When you say "the sync between docs and devs happens via Jira", what did that look like in practice? Was Jira mainly used to coordinate documentation work, or did you also establish traceability between Jira work items, documentation changes, and releases?

I'm curious what that looked like in practice.

[Kris Klima _K15t_]

Hi @Evelin Bayer - codefortynine 

On the governance... it's all DocOps, and I took it with me from CA elsewhere.

A tech writer is assigned to a dev team (product/feature, depending on the org structure), ideally 3 teams max. That means that a writer becomes a part of that team. They attend all (most) agile rituals - groomings, plannings, retros, standups. So when estimates and velocities are considered, they're there to say 'will need a week to write it'.

Every dev Jira ticket (Epic, Story, depending on granularity) for a new feature, update, or deprecation, had a documentation ticket. That doc ticket sits on the dev team's project - it's not the documentation team ticket, it's a dev team's documentation ticket. Subject to all stages of the process, including QA. And it's a part of the definition of done. So the dev team cannot close their story of the doc ticket is not closed.

This have a couple of positive collaterals.

• documentation is a part of the product
• writers dramatically increase their product knowledge
• devs and others are exposed to documentation work all the time
• and they tend to become rather helpful to keep their score good
• it minimizes the chance a feature is released without docs

I introduced the process at Emplifi and frankly, over almost 3 years, we had just a few accidents of a non-documented minor update - when a devs basically acted without a PM knowing because they thought it's a minor thing :D 

It's even better on Cloud where integration between Confluence and Jira is really great (reviewing pages from a jira ticket...)

As for the other points:

Nesting macros

There are limits in Confluence but, with a couple of notable exceptions, I'm not huge fan of nesting information ;)

Reusable content and traceability

Ideally, you create a library of reusable content to help with the cause but it's not great. Excerpts / Insert excerpts can be traced as outgoing/incoming links. Synced blocks are much better.

Conditional content

AFAIK, our Scroll Content Manager (its Variants bit) is the only solution that provides that functionality. The 'who can see what' is not conditional content in my book, that's a permission setup. More on this here in my older Community article about conditional content in Confluence.

Disclaimer: I work for K15t, maker of Scroll Content Manager.

Avoiding broken links

Check the page details for the list of incoming and outgoing links prior to archiving/deleting.

This is turning out to be an interesting tech writing conversation :)