Overview
Welcome to the seventh article of the 3x3 series – Confluence for Designers looking at the communication structure for medium and large organisations to achieve transparency, which leads to frictionless and smooth design delivery.
This article will be opening the third and last pillar that utilises – Development [001↘︎], Releases [002↘︎], and Integrations [003↘︎] sections, building from what we have discovered, acknowledged, redefined, tested and designed to this very point.
“Documentation is like sex:
when it’s good, it’s very, very good;
when it’s bad, it’s better than nothing.”
— Dick Brandon
Every product team aims to empower developers to deliver well-written code that is easily deployable. The focus here is on the handshake between these two different functions and mindsets that neither one wishes to document.
In the same way, as the Design or Experience section is design-led, the development section has its specifics. Especially when it comes to setting up the environment, listing the APIs or reporting the releases in one place – every team I have worked with has a different method how documenting code.
Note of the author: Please acknowledge that the fact that whether I can read the code does not make me a developer. I have been fortunate enough to work with some very talented people in the industry who positively influenced my perception of how best we all can collaborate together, and for that, they have me undivine respect. The following is just a glimpse of what the unified knowledge base could become.
What does the Development Section do?
This section is about the development and how the entire thing is set up. Starting with High-Level Requirements – HLRs[004↘︎], System Level Agreements – SLA[005↘︎], TDD[006↘︎] or BDD[007↘︎] agreements in place and technical parameters for each release.
Many development teams came to me throughout the years and commented on the structure. Sharing their ideas and insights would help them to be more connected. The majority of them were amazed by the level of consideration of all disciplines and the transparency model between them using my advice and previous learning. Document resources, APIs, calls, scripts, security protocols, databases, and even linking all notes from BitBucket or any other code repository – all well automated with algorithms to reduce the complexity of documenting and sharing.
Structure:
/ HLRs – DOR, DOD etc
/ SLA + SLR ≠ System Diagrams
/ iA + Task flows
/ Backend – Vercel, Google or Azure settings
/ BackUp notes (automated)
/ Front-End – testing mirrors and
/ Release notes (automated)
The overview of the section starts with HLR [008↘︎], which defines the project or product. That also set’s the tone for what methods and routines are used—listening carefully to Product Owner – CPO[009↘︎] and Scrum Master – CSM[010↘︎] makes a massive difference.
“I often advise designers to question everything in this stage as its defines how well they are integrated within the team.“
SLA[011↘︎] + SLR[012↘︎] – for non-tech led designers, SLA stands for System-level agreements. I encourage my team to read these documents to find out how best we can solve the customer problems by understanding these written definitions.
iA[013↘︎] – previously mentioned in the Experience section [014 ⁇ ] has a different meaning in the development world. I’ll encourage you to run this test as a maturity evaluation of your team. “Ask each team member what is the definition of Information Architecture – in other words, what do they mean if they mention iA to someone in the team?” [015↘︎]
Back End – is all bout the logic and how the entire system works. Whether you have a full-stack developer (doing pretty much everything) or a dedicated team of backend engineers having a divided subsection is good for understanding what happens behind the curtain and what you can influence.
Front End – I’m seeing FE Engineers more like Creative Technologist [016↘︎] nowadays. And therefore, their world is very much linked with ours, which makes us integrated from the very beginning of the project. This makes their reporting / documenting slightly more manageable as they have full access to our work which they can and should reuse.
Above all, the section must include links to real code examples, features, prototypes, and versions to document and see the progress of the real invention – the latest iteration of the product or service we are currently building.
The Dev. Section Does not include.
I’d like to take the opportunity and talk about a particular challenge in documenting, and it's the language barrier. Most of the time, poor documentation does not mean poor language (in our case English).
Millions of designers and developers are not native speakers, even more, native writers. As it is close to my heart, I have wrongly avoided it too, for some time. I was afraid to describe the functionality because I had no extensive vocabulary to do. Even more, learning English through French as Czech gets even more confusing. Despite my insufficient vocabulary, I always wrote simple notes next to each snippet of the code or wireframe I made. And that’s how I got better.
I was part of the remote development team and had profound resistance to documenting anything – not because there was no understanding or knowledge. They are tremendous backend developers with extensive knowledge in data migration at scale. Yet, describing what they have done in English becomes extremely challenging, if not traumatising.
My approach to such a challenge the team was to divide the problems into two categories. Things that happen and can be automated and therefore communicated without extensive description – were a significant win. The team put themselves forward to find appropriate JQL – Jira Query Language [017↘︎] and automate the hell out of it.
The second part took longer, and it was worth every minute spent on it – as it made the entire team closer. It encouraged writing simple notes about what was done and how to extend the note, what needs to happen, and why. Soon enough, we have snippets (in other words, paragraphs) that other team members like BAs and CX designers can take and amend in no time and start building a so-called knowledge base.
Reaching sprint 6 (week 12), we gave the team comprehensive documentation between three continents, timezones and languages.
Three things happened:
Well-diverse teams were now glued to the one source of truth, which reduced the communication overload on other channels and focused on the knowledge base.
Simultaneously, the team saw that the knowledge base saved their production time. They were not forced to look for the information further and started building interest in documenting exclusively as a part of their daily routine.
Followed by the celebration of the first release, all members agreed that we reduce meetings to 5-10 min catch-ups in the morning (StandUps) and evenings (DropOffs) where each developer presented what has been delivered – the increment [018↘︎]
This creates a set of new challenges, but every business wants to have these challenges – engaged contributors strive to deliver their best without ever feeling not enough concerning their location, language barrier or outputs.
Quote
“We can easily forgive a child who is afraid of the dark; the real tragedy of life is when men are afraid of the light." – Plato
For more information, please join the Design at Scale™ Courses that explain the function, impact, and common pitfalls that can be avoided while implementing the DaS™ in your business.
Structure
Let’s look at the Confluence structure in detail:
Business
1.0 — BRAND* Hello 2.0 — BRAND* Business 3.0 — BRAND* Research
Design
4.0 — BRAND* Content5.0 — BRAND* Experience
6.0 — BRAND* Design
Development
7.0 — BRAND* Development
8.0 — BRAND* Releases
9.0 — BRAND* Integrations
I hope you’ve enjoyed the fifth article from 3x3 – Confluence for Designers. @designatscaletm is open to discussion about detailed implantation. The following article will focus on the Release section and all information related to tracking, ever-seeing, and maintaining transparency.
See you there.
