May 10, 2021
Atlassian Documentation for Product Design Teams Part 5
“Documentation is like sex: when it’s good, it’s very, very good; when it’s bad, it’s better than nothing.”
— Dick Brandon
Welcome to the last the fifth articles of this series. Over the last four weeks, we went through the history and definition behind this Confluence structure. Helping the colleagues with a business mindset to have an extra lens on the product and development through the supporting parts of Hello, Business and Research sections. Followed by the folks with a design mindset that are organised around the Content, Experience and Design Section to help the definition of the product. This all is now followed by the structure that increases transparency between Design and Development teams. Any product team aims to empower the developer to deliver well-written code that can be easily deployed. The focus here is on the handshake between these two different areas.
Over my career, I have met two types of developers, those who like documentation and those who don’t. The truth is that some code is so well written that it doesn’t need extensive documentation. However, a genuine product person will not understand complex solutions that use amp cache, Cloudflare or integration with Vercel. Then, documentation becomes a necessity.
Some code is so well-written that anyone can read. Yet, how many developers would allow the marketing guy or designer to read their code?
7.0 — DaS Development
This section can be genuinely one of the most significant areas in your Confluence space. It’s fair to say that it will reflect your business’s culture and the ability to share. Throughout the years, many development teams have come to me and commented on my structure. The majority of them have used my advice and previous learning extensively. Document resources, APIs, calls, scripts, security protocols, databases, and even linking all notes from BitBucket or any other code repository.
The most significant collaboration with developers comes from defining what they need from the business, designers and researchers. This development team showed not only maturity but ownership over the entire proposition.
Value the developers who extensively communicate and challenge the proposition!
— CPO®, GS 2012
8.0 — DaS Releases
Outside of Business and Experience, this is the essential part of Confluence, where everything intertwines. For the first six years, this section did not exist. With an increasing need for performance monitoring in JIRA, this section becomes a monitoring hub for all releases. Simply put, for less mature teams, we created a single destination that unifies the picture in the most digestible ways possible. (and no one has to visit JIRA anymore)
The pages hold the release names MVP, Alpha, Beta, CR1.0, CR2.0, etc., where each release has a list of Epic and User stories in the form of a list. A separate page with JIRA macro monitoring current status. Finally, the page with all blockers simply highlights the obvious–what needs to get fixed before the release.
Apart from the challenging explanation that highlights all sorts of problems, I have never recalled significant issues with this section. Please feel free to ask questions to get the best out of your confluence space for your product.
9.0 — DaS Integrations
Nowadays, it is impossible not to be integrated, not to use an API to link your product with social channels. This section is summarising the product or service integration with 3rd parties API and services. Even if your product lives outside, it eventually needs to be integrated, and this section defines how and why. This section was always first to be filled by the developers. Lately, as we use more and more connected services, this section defines the success of the product compatibility and integration.
Common Questions
Meetings and notes.
For several years, I have run all meeting notes in Confluence linked to calendar macro or simply set up an epic in JIRA to summarise all meeting notes in one palace. Whichever method works for you, it’s the best way to get track of all the sessions that have taken place, and, from time to time, that means the existence or continuation of the projects.
The learning curve is that we all take the notes in the notepad, iPad, Evernote, or simply scribble post-it notes. Either way, if we happen to have them on the same platform, we’ll have a better picture of what is happening. Otter.ai has become an indispensable tool that records all our meetings. It allows us to focus on solving the problems instead of scribbling the notes.
Impact measuring
Have you come across these questions, or you were just scared to ask. Where are we with the build? How much design is left? Have we done sufficient research? How much money do we need for testing? Are we under or over resourced? And so on.
Once everyone contributes in one place, it’s much easier to monitor these things instead of running a separate system with separate timesheets and different formulas communicating simply one thing.
Atlassian, with their macros, has built a comprehensive place not only for developers but for the entire product team–use it, and you might be surprised how much energy you might save to yourself and to your team.
Tools and plugins integrations
Throughout twenty years, I have tried a dozen of applications on all different ends; design, time tracking, assets management, development, monitoring and so on. I prefer to have a few reliable well-integrated tools than various independent solutions that look stunning but always crack when you scale from 2–20–200.
The learning curve here is to “choose the tool that you can master, not the one that makes you servant”.
I hope you’ve enjoyed this little series about Atlassian documentation for Product Teams.
1.0 — Hello
2.0 — Business
3.0 — Research
4.0 — Content
5.0 — Experience
6.0 — Design
Development
7.0 — Development
8.0 — Releases
9.0 — Integrations
I hope this set of articles help you to paint the picture of how to save more time while building your digital product, get more efficient don't lose yourself in a countless meeting with no single tangible outcome.
Stay tuned; thanks for reading!
Thanks to all contributors especially Matt Press, for their insight and comments shaping this very article.
Jiri Mocicka is a London-based designer writing about his passion for the Design at Scale — integration and design operations that builds excellent digital products.
