RFC-2: Restructuring CDAC categories

ibuchanan · January 31, 2023, 4:18pm

RFCs are a way for Atlassian to share what we’re working on with our valued developer community. Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Summary of Project

As a step toward bringing consistency in information architecture across Atlassian ecosystem tools, we propose a new category structure for the developer community based on the organization of developer documentation.

Author: 3 Feb 2023
Publish: 3 Feb 2023
Discuss: 10 Mar 2023
Resolve: 24 Mar 2023

Problem

For developers the current Developer Community is disorganized. It does not match Atlassian’s current way of organizing our products, people, and programs. This ultimately leads to poor signal-to-noise ratio and prevents the community members from leveraging the tools (subscribing to categories and topics) that can help.

For Atlassian, the inconsistent information architecture adds friction to publishing all kinds of content, including documentation, broadcast announcements, and collaborations like RFCs. When it is hard to publish, then it gets done less often or in less timely fashion.

As a result, it becomes harder and harder to publish new information about new things (like a new product) while attracting new developers who will find increasing complexity. This needs to be solved for at least this discussion forum so that we can more quickly publish, find, and address developer problems.

Proposed Solution

While we consider broader and deeper solutions across multiple channels, an initial step would be to take the developer documentation as the “template” for categories in the community. As a reminder, “category” in Discourse (the tool used by the developer community) is the organizing structure for “topics” as the threads that developers start and comment in. Currently, the top separation for docs is “Cloud” and “Server”, then the next layer is approximately “Product”, “Platform”, and “Resources”.

Meanwhile, the top level of the community is a mix of products, programs, and concepts. Some product categories are further subdivided by “Cloud” and “Server”, some aren’t, which often leads to poor segmentation of topics. For example, because of Discourse navigation, many community members only select “Jira Development” without picking the right subcategory for “Jira Cloud”, which can lead to unnecessary back-and-forth for topics like REST API auth where the difference really matters. On the topic of Jira, this also misses the distinction used in the documentation between “Jira platform” and specific Jira products like “Jira Software”, which leads to additional confusion while trying to ask and answer questions.

Clearly, this will introduce many changes to the current category structure:

Following the documentation structure, the new navigation would resemble (the following is not necessarily exhaustive):

To call out a few notable differences from the developer documentation:

General. Unlike documentation, we want to make room for conversations that may not be specific to any product, platform, or resource. This category already exists.
Data Center. The term “Server” has been used to mean “Server and Data Center”. Going forward, “Data Center” is the product category that remains for the foreseeable future.
Labs. We need a place for “work in progress” so that we can talk about products and programs that are not yet fully released. For now, this would include RFCs like this and early access. This would be an area that itself needs to grow and evolve, with some categories living here only temporarily before finding a home under the more stable categories. Also, Atlassian would be looking for a different type of conversation than the typical “question and answer” found in the rest of the categories.

As a constraint, Discourse limits the category structure to two layers. As such, the lowest nodes in the diagram are representative of actual categories. All middle categories would be combined like “Data Center Products” or “Cloud Platform”.

We will be using this opportunity to consolidate Announcements. Currently, there is a top level category for announcements, plus many subcategories within other categories, such as “Bamboo Announcements”. This reorganization will move all announcements into 1 category under General. We will work toward better tagging in the announcements to help reach the right target audience, without overloading consumers with too much noise. Other than reorganization, improving the announcements is not in scope for this RFC.

Staging the new structure

Make sure the new structure works “in situ”. Atlassian would rework a copy of the site and making that site available for review. This staging site will provide opportunity to rework the existing structure and to revise some of the category “about” topics. We will restructure the content only using automation so that we can be sure no content is left behind.
Scheduled planned downtime for the community. Once proven on a non-production site, the automation would be applied to our live site during a scheduled weekend outage. The timing and duration are to-be-determined.

Actions

We are seeking input on:

Do you see any serious flaws in this proposal? What can we do to mitigate them?
In the developer documentation, the distinction between “platform” and “resource” seems a bit blurry. How would you define these 2 categories better so topics can be better classified in both dev docs and the community?
The name “labs” has baggage for Atlassian, with Atlassian Labs already existing in Marketplace. Is it confusing to use that term for RFCs and early collaborations? What title would better convey the experimental nature that sometime early ideas don’t make it to production?
Do you agree with this proposal? If so, a like is sufficient.

AaronMorris1 · February 10, 2023, 9:37pm

Hi @ibuchanan ,
(Deleted my first post, because I realized you and I asked the same question. Sorry!)

Re: Platform vs. Resource: Yes, these terms are terribly blurry, and I would add “Product” to that list as well. When it comes to app development, it’s often difficult to cleanly distinguish between “Product”, “Platform”, and “Resource” (the primary middle categories in this proposal).

To answer your question:

First, I wouldn’t be overly concerned with aligning the structure of the developer docs and the CDAC. I can see how CDAC announcements could possibly be organized in alignment with the docs, but community questions may be nearly impossible to align. (It’s too difficult for askers to know whether product, platform, or resource is at the root of their question.)

Second, I suggest organizing the CDAC categories to align with how Atlassian wants to monitor them. (e.g. Perhaps you can loosely match some internal structure within Atlassian?) This could make it easier for the right Atlassians to subscribe to the right categories.

Third, regardless of how you structure the new categories, I recommend that Atlassian should publish a new resource that:
a) describes the new category structure
b) provides a clear description of each category
c) provides examples of topics that would belong in each category
d) provides examples of topics that would not belong in each category

If the CDAC is organized in a way that is convenient for Atlassian to monitor it, and if there is clear guidance for the rest of us, then there’s a good chance everything will come together well enough.

Re: “Labs”: Perhaps this can just be removed as a category? For now, RFCs and EAP can easily stand as their own high-level categories without being group together (IMO). And if something new come along that doesn’t belong in RFC or EAP, then maybe the answer will become clear at that time? (Unless you already have an example of a “third” category.)

ibuchanan · February 12, 2023, 11:15am

@AaronMorris1,

Thank you for the reply. You’ve provided some great insights!

I think the most difficult aspect of this re-org is the tension between your 1st and 2nd points. Specifically, the Atlassian org structure (which largely informs how we want to monitor) has many internal-only quirks that lead to the kind of difficulty you point out:

It’s too difficult for askers to know whether product, platform, or resource is at the root of their question.

That said, your 2nd point is the reason I am “overly concerned with aligning the structure of the developer docs and the CDAC.” I didn’t really explain it well in the RFC, and now that you raise it, I doubt I could have identified that motivation until you said it. Hence, my resolution to the tension is to try to do 2 things. First, expose the “ugly” org structure, even if it is hard for developers to navigate because that will be the best way to align with internal teams who need to monitor, which in turn should improve the answer rate (or at help teams motivated to answer keep focused). Second, apply the advice in your 3rd suggestion. Trying to explain “platform” vs “product” will be difficult but perhaps the effort to do so will help Atlassian better organize toward “stream aligned teams” for developers. I’ll happily pull your 3rd suggestion into the RFC.

The simplicity of your “labs” solution is compelling. And you make a great point about trying to organize a category with too few members. RFCs are the platypus in our animal kingdom of the CDAC world.

bentley · February 13, 2023, 3:43pm

I wonder if this can’t be achieved with some heavy-handed custom theme-ing. That might be a ton of work that still requires underlying data re-architecting at the end of the day, but might be worthwhile as it would allow all of us to give it a try on a day-to-day basis.

Does this new architecture align with the changelogs architecture, as well? For instance, Confluence Cloud changelogs can be found at https://developer.atlassian.com/cloud/confluence/changelog/. I often think of this triad (documentation, CDAC, changelogs) as the core components of Developer Experience.

I believe that it does since changelogs are embedded in documentation’s architecture. But wanted to ask out loud to double-check.

ibuchanan · February 13, 2023, 4:09pm

@bentley,

I think it’s easy to verify the alignment today. But I think your question is a little more long-term. Fortunately, even over time, I think the developer docs “force” a structure on the changelogs since, as you point out, “changelogs are embedded in documentation’s architecture.” In other words, I can’t imagine a changelog (except the universal changelog) without a section in the dev docs. And, if it were about to happen, we’d force changelogs to fit the dev docs, either by creating a new doc set in the docs, or creating the category in the changelogs. I’m convinced they are tightly coupled.

While I considered it “an implementation detail”, I did want to explore how the automation that drives the reconfiguration could be leveraged to keep the community in sync from a common source of categories (as components). But even for a single source, a question remains about how that source would be managed. If we had such a single-source, and it were authoritative, then I would be inclined to make it public. For now, I think that’s all out of scope of this RFC though.

ibuchanan · March 10, 2023, 4:51pm

On schedule this time, I’m closing RFC-2. As of today, there were 341 views, 11 likes and 3 commenters contributing 5 comments. Even with lower contribution than other topics, I learned important aspects about what the community values and how you want to use this site. I’ll be preparing a resolution to this topic over the next couple weeks. Please stay tuned for resolution or before 24 March 2023.

ibuchanan · March 24, 2023, 8:13pm

What did we learn?

Overall, the community wants more Atlassian engagement as answers to questions, or actions to fix bugs. The structure itself is, at best, a means to that end.

What did we change?

We did not identify any serious flaws. However, we do not have the capacity to engage in this project at this time.

What is coming next?

At this time, there are no specific future plans. If reorganizing categories proves useful on the path to better Atlassian engagement with the community, we believe we have confirmed a reasonable plan. The general sentiment seemed to be that cross-channel alignment of information architecture is a good idea.