Skip to end of metadata
Go to start of metadata

A few weeks ago a technical communications industry-shaker book was released!

"Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication" is a book by Sarah Maddox, the brain, brawn, and head information architect (along with the killer tech doc team at Atlassian) behind Atlassian Software's extraordinary technical documentation set, developed and delivered on Confluence Wiki, and supporting over 10 products, developer documentation, and more.


Following is a story and by the end, book justification vs. review.

It is a story of a situation that likely resonates with many current or past tech writers – as well as marketers and execs, since truth be told, documentation affects all sides of a business.

This is a story about the love/hate realities of niche documentation tools, process knowledge, and all too common lone-soldier documentation roles. It is a story about the personal, professional, and corporate limitations and risks to this paradigm – and the many more opportunities available with a collaborative documentation strategy.

Sarah's book provides fresh industry perspectives for healthy documentation strategy freedom, and vital keys to her craft. Her book is a 476-page enabler to build a documentation set as great as Atlassian Software's.

Making "state of the art" documentation, back then

A little over 5 years ago, I was first introduced to Atlassian Confluence (and JIRA).

At the time, I was a newly hired product manager at a unified communications/voice messaging company in Cupertino, CA.

Prior, I'd had a thriving tech. doc consulting business for 10+ years. My experience came from great name corps, like AOL, Apple, Avaya, Cisco Systems, ChipX, Cylink, ECTF, Kineto Wireless, Motorola, 8x8, Octel, PublicMind, Symbol, Symantec, Visteon (Ford Motor Co.), and more than a dozen lesser known startup corps...

As a self-employed contractor, I’d always been tossed the gnarliest of tech doc challenges – which honestly, suited me just fine. The harder the problems, the better and more vital my skills became, the more contracts came my way. Work was endlessly steady, even through the dot-com bust. I’d often juggle 3-5 clients at a time. I was in my element.

My main tools: Adobe FrameMaker, Adobe Acrobat, and the ultimate niche skill product: WebWorks Publisher.

The new company I was joining had been my client for the previous 1 1/2 years. I owned and created their doc set from scratch, with all the latest and greatest flexible-doc bells and whistles:

  • single-sourcing
  • conditional text excerpts and flexible variables
  • integrated context-sensitive links from product dialogs
  • multiple graphics formats
  • auto-compiling doc builds
  • multiple platform/format outputs: online help, Website HTML, PDF, and print

It was versatile, friendly, and searchable with custom navigation features. It was polished. 

It was state of the art at the time, in tools, practices, and results. After all, I'd learned from some of the best high tech corps of the times!

The ominous onus of niche tech doc skills

I knew the company's product like the back of my hand – afterall I'd doc'd (and tested) it from all angles.

My conscience was clear – I could leave the doc behind with good faith, and dive into PMing fully.


Truth be had: NOT so fast!

Months later, a replacement tech writer job req had still not been opened! My management kept telling me "We'll hire; I assure you." But it never happened. I felt duped, and extremely challenged by the reality of my "stuck" predicament.

In-house, I was the only one that knew how to use my tools, update docs, even cross Ts. No one knew how the tools/doc process worked, compiled, ran, published -- and no one wanted to know!

I also knew that finding someone with WebWorks skills was close to impossible. It was the most sought after tech doc skill in the valley, and those who knew the tool were never available. I knew – I'd been one of them!

I was willing to train someone, but clearly my management thought differently: Why pay to train when you already have someone doing it great?

I was caught in the “hostage twist of the trade": cornered in a role because my skills were too specialized.

While deciding my next career move, I supported 40+ engineers in all product documentation efforts.

What? Confluence for official product documentation?

Confluence meanwhile was picking up pace for internal project management efforts. I started getting excited about the wiki and all it had to offer (even at v2.1!). 

About the same time, I learned of Sarah Maddox, a senior technical writer at Atlassian.

Sarah had a blog, providing sage and experienced tech writing advice. We used different tools, but I really identified with her way of thinking.

The Atlassian documentation team were in the early stages of building their product documentation set on Confluence Wiki.

Building official product documentation on a wiki?! This was new, and interesting:

  • I noticed that their wiki documentation was exposed to the Web, and changes were often made on-the-fly. They would do releases, but they could also make changes after a release. Unheard of!

  • I noticed that the online wiki doc was the primary format, but they also provided PDF and XML outputs, and context-sensitive links.

  • I noticed how certain components were templated ("excerpts", "includes", "user macros"), so "content blocks" could be shared in other docs or sections.

  • I noticed how easy it was to find things with Google, and that all content was SEO indexed regularly. Atlassian documentation always ranked high in search results.

    I recalled how Cisco did something similar years earlier during their rise. As one of the first networking companies, Cisco quickly gained credibility as THE defacto networking industry expert by overwhelming the Internet with their voluminous content and PDF documentation (among other reasons). RIM and BEA Systems were other corps that took this strategic approach, also having fast early momentum.

  • I noticed how engineers and PMs -- without special doc tool skills – would lend a hand, and update the doc themselves sometimes: fix wordings, typos, clarifications, add sections. In general, help – a notion that was completely foreign to me as a lone soldier.

  • I noticed how Atlassian was having above average fast success for a still very young company at the time. The doc had to be driving some of that Internet traffic and success.

  • I noticed how fast Atlassian was releasing product iterations. I figured that the increased documentation visibility and collaboration was naturally pushing better momentum in the organization.  

  • I noticed how Atlassian was also growing an active online community by allowing comments on the public doc wiki pages.

And a whole lot more. I didn’t know any companies at the time that was doing doc this way (yet!)

It was cutting edge, bold, powerful, and strategically AWESOME!

I watched Atlassian documentation evolve that year, and was envious. It pained "my stuck" feelings even more:

  • I started realizing just how deep my hole (and the entire tech doc industry hole) was. 

  • I started realizing just how inefficient niche tech doc tools and processes had become, ironically.

  • I could see that efficiencies well beyond the doc teams' efforts where being accomplished at Atlassian using these wiki approaches to documentation.

Clearly, "documentation" was not the only thing Atlassian was building through their documentation set!


I wanted to use the wiki for our doc, but I wasn’t allowed. I wanted the engineers to collaborate on bit pieces for the doc, and even that was trumped down. In fact, almost every time I added anything to the wiki, the Sr. PM would come to my desk and ask why I wrote something in the wiki; it was only for product management. #SeriousInsultToInjury

"What?! It’s a collaboration tool – that’s what it’s for!"

For a bit, I thought I was nuts. But I also knew that the Atlassian documentation progress I witnessed that year was not nuts.

After a year, I finally left that company/nuthouse! – with a new career passion in my sight: Atlassian Software!

Building a goldmine!

At a higher level, I considered Sarah Maddox to be one of the most brilliant and daring documentation professionals out there!

And Atlassian was building a goldmine in their web-based wiki documentation assets. 

Fast-forward 5 years... the proof is in the pudding!

  • The Atlassian documentation set speaks for itself.

    It is truly a phenomenal technical documentation set/reference implementation by any industry measure.

  • Atlassian as a corporation is now a globally well-known fast tracking success-story that has quadrupled in size since -- with far more in sales success -- even despite "the GFC".

    Sure, their great products and marketing help in this success, but as a company selling Enterprise software on the Internet, their documentation is an enormous contributor to this success without a doubt.

Morals of the story

While there's numerous points to this story, here's a couple key takeaways:

  • For tech writers/corporations stuck in linear old non-collaborative doc process paradigms, there's hope!

    With iterative collaboration and shared purpose deliverables, business goals, and processes – incredible efficiencies, teamwork, value, and new opportunities can take root through the documentation process.

    With management support – the potential of documentation (and you) to your organization is endless! And that’s how it should be!

  • If your management does not support you, leave. Run, do not walk, and find your path!

Who should buy this book?

Check out Sarah’s book -- for best-in-industry perspectives, valuable tips, tricks, recommendations, and a whole ton more on being successful using Confluence as a documentation platform, and beyond!!

476 stocked pages! Here's the link on Amazon.

I don't think there is any bigger power user than Sarah!

Are you ...


Atlassian customer

If you use Confluence - or considering Confluence in the future, learn about the endless opportunities with Confluence, for documentation and well beyond.

Technical Writers

Regardless of where you work or live in the world, if you are currently using conventional technical documentation tools like FrameMaker, Word, Webworks, Robohelp, MadCap, or the like, learn more about strategic documentation practices with Confluence.

Product Managers

If you are responsible for end-to-end product deliverables, including documentation, you should read this book for new perspectives. Optimize your team collaboration and product documentation, with greatest results.

Marketing Professionals

If you work in a company with documentation "behind the firewall", and large business growth objectives, you should review this book. By not having your documentation public, you are missing a massive SEO opportunity, in addition to an opportunity to show yourself off as a technical expert in your industry – among much more!

Executive Management

If you want to increase your brand, sales, marketability, and overall business growth, read this or give it to your team to evaluate it. Sarah's book has high strategic value.

If you fit in the above list, this book is a must have.

  • No labels