[RESOLVED] RFC-1: Request for comments (RFC) as early collaboration with our Ecosystem

General Request for Comments (RFC)
,
8

@james.dellow,

how will the Atlassian team know when to raise an RFC?

That’s a very insightful question. And I agree that “doing it well is hard”, but our hypothesis is that a standard “RFC process” can make it easier. While researching this, we identified RFCs are well-known on the Internet and inside Atlassian. Even without calling them RFCs there are teams who have good habits about early collaboration with developers & partners. In this first stage, we are trying to prove we can make things easier for those already motivated teams by helping do each of the “stages” faster: author, publish, discuss (respond to comments), and resolve. By removing many decisions that don’t really add value (like essential structure, where to publish, whether to respond, and whether to resolve), we think it will reduce the cognitive load.

Behind this RFC, we’re also building out some analytics so that we have the kind of data that convinces more Atlassians the process is worth following. So after some number of RFCs from the parts of Atlassian that already engage the community, we’ll take on spreading the practice into the parts that don’t. So far, I have seen a good deal of evidence that more teams would engage, if only they had some guidance. Unfortunately, Atlassian is large enough now that I could not provide that kind of guidance directly, at the rate of demand. Hence, declaring standards like this RFC process itself is a “self-service” mechanism to help spread the practice.

I realize that “working the process” is still short of a solution to “doing it well”. My thought here is the mantra I’ve often heard from the agile community, “If it hurts, do it more often.” The implication being that practice will solve the “doing it well” problem. That said, I would be happy to take input. What advice would you provide to Atlassians about publishing their first RFC?

2 Likes
9

Would Atlassian (@ibuchanan) go as far as limiting changes to ecosystem technology to resolved and accepted RFCs only?

2 Likes
10

@UlrichKuhnhardtIzym1,

Short answer: not quite that far.

While I appreciate the sentiment, I think you’re putting a lot of trust into a process that has only just begun. If we tried to go that far right now, I think it would just bounce us from one poor extreme (too much uncontrolled change) to the other (too much “big batch” change).

In the near term, we need to focus on making the RFC practice “work” both in terms of getting the “cost to author” lower and the “value of participation” higher. On the side of authoring, we’re already learning from the first 4 RFCs about the kinds of written guidance we can provide. On the participation side, we’re looking at “wiring this up” to some of our existing data collection tools to make sure this continues to work at scale.

In the longer term, I think we could consider a model of “RFC required”. But I think we’re going to need more surrounding standards & practices. For example, I think we need a better “lifecycle model” around the products & technologies in the Atlassian ecosystem. Some components might need to evolve very quickly in a mode of “pioneers”, with only a small set of highly-engaged partners, and without the formality of public RFCs. While other components have found their market-fit and need to evolve carefully with a large set of self-service partners where the model is more “town planning”. We could consider “RFC required” for this subset. In other words, I think we need to better account for the variation in Atlassian and the developer community before we would resort to “one size fits all” requirement of RFCs.

All that said, I am certainly hoping for a bit of “community enforcement” even now. It is perfectly reasonable for anyone to ask Atlassians, “Why didn’t you engage us sooner with an RFC on X?” Indeed, I hope you will.

3 Likes
11

Flip side of @UlrichKuhnhardtIzym1 question - how can we make sure that Atlassian doesn’t abuse these RFCs? I’m slightly concerned that we end up getting 500 RFC’s a day and things get implemented by Atlassians going “Nobody spoke up and they had their chance”. Ie. Can we please make sure that the RFCs are not the only way that Atlassians seek out input.

Thanks,

/Daniel

12

@danielwester,

Can we please make sure that the RFCs are not the only way that Atlassians seek out input.

I realize Atlassian has done that kind of thing with EAPs in past. While I’m in complete agreement on the “not the only way”, I’m not sure what to do about “please make sure”. It feels like the perpetual dilemma of “can you make sure you do enough testing”. I think (or hope) we all know, “you can’t test quality into a product, you have to build quality in.”

I think that’s a bit the same here. With Developer Experience (including me) acting as your advocates, we can keep an eye out for that disingenuous application of RFCs. But we are a small team and I don’t think we can “prove the negative” anymore than a QA team can. Generally, there is always the problem that asking us to check ourselves is asking the fox to guard the henhouse.

What we’re trying to do here is “make it easier to do the right thing than the wrong thing”. To that end, we are working on other complementary practices to RFCs that should cover cases where RFCs won’t work, provide more (and predictable) points of interaction, and do more to “build quality in” (rather than focus on checking for it).

1 Like
13

Hi @ibuchanan -

Watching this new process unfold, I think I’ve noticed a minor technical flaw:

I’m finding that monitoring RFC’s for edits is very challenging. It seems that the forum 1) doesn’t highlight a post as unread when it is edited, and so I think you need to click through RFCs and look for the little edit icon . And 2) it doesn’t make identifying the edits easy (i.e. viewing redlines).

For example, I’ve already reviewed and commented on RFC-2, and I can see that you made edits 6 days ago. But is there a way for me to know what your edits were? (Did you address any comments or were you just fixing typos?) The tool doesn’t make it clear.

Again, just a technical problem, with possibly some procedural solutions. Or maybe just user error (mine)? :slight_smile: I definitely agree with the proposal of keeping RFCs updated.

Thanks! I really appreciate that you’re giving this new process a shot.

2 Likes
14

@AaronMorris1,

Keeping track of edits is an important point and one we decided set aside for the sake of getting something out the door quickly. I assure you that it’s not something you’ve missed; Discourse just isn’t made for the kind of “change tracking” that would best fit. Fortunately, we have not had an RFC undergo “major revision” or everyone would notice. We’re considering switching over to Confluence but that will create “yet another channel”. For now, we’ll try to do better with some manual notes about edits.

2 Likes
15

Another option would be to either create a comment with the adjusted RFC, or close the RFC and start a new thread. Would that be an option?

16

@remie

Possibly.

For very small edits, like the one I remember making on RFC-3, it was just tagging and a little formatting where I’m not sure a repost would make sense. I don’t remember changing RFC-2 in response to @AaronMorris1; maybe I clicked edit on the wrong post and didn’t “cancel”? In any case, the tool’s memory of “an edit” is confusing and could still lead to people wondering about the change.

I’m leaning toward this, option as the right way to handle a serious redraft, as we will need for RFC-1 to account for all that we’re learning with these first RFCs.

I’m still drafting some observations & learnings (including on prioritization; I haven’t forgotten). From the authoring perspective, what’s feeling “right” is to pull out a section for reposting & subsequent comment, which fits somewhere between your 2 proposals.

And, one of the considerations I’m trying to hold in mind is the importance of resolution. Without experience on trying to draft one and tie-up all the loose threads & thoughts, I’m not sure how any of these style of revisions would fit.

Overall, I’m inclined to try both of these suggestions. I think RFC-1 would benefit from “close and redraft”, likely after the end of the discussion date, therefore creating a new timeline. And RFC-2 from “edit as a post”, the scope of changes is shorter.

1 Like
17

Oh gosh. Please don’t start a new thread. We’ll be overloaded by Atlassians creating new threads as soon as they’ve tweaked an idea slightly. We’ll end up having to have versions of the threads. There will be multiple versions of conversations going on. It will be what I expect from Atlassians abuse of a forum.

Can we please use something that is meant to do proper versioning of documents and commenting? If not Confluence - Google docs?

2 Likes
18

Discourse supports edit history just fine (including a neat diff), I think it has simply been deliberately disabled (or limited to staff) on this site?

I always wondered what the rationale behind hiding the edit history is, so provided there isn’t an important one, you could enable it again and just add a comment for any significant edit so that watchers are notified and can check into the diff.

5 Likes
19

@danielwester,

No, not new thread for slight tweaks. I’m not committing to new tooling but it’s on our backlog. There are more “moving parts” here than are apparent so I appreciate your patience so far.

@sopel,

Discourse support for diffs is news to me! I’ll look into it.

1 Like
20

This morning, I closed the first “real” RFCs:

While we wait for resolutions on those specific topics, I wanted to reflect a bit on what we learned from the first discussions. Overall, RFCs seem to be going well. Internally, we have additional topics lined up, and we’re creating more guidance as we learn, so each new one will be better and better tuned to a useful collaboration with the developer community. Externally, we had high participation that has lead to genuine learning and improvement.

Constructive input

So far, we have observed some commenting patterns that really pleased us. We saw a lot of examples of constructive comments. The following reflects some of the engagement patterns that were really helpful.

  • Asking for more clarification in areas where commenters need to understand more. We might not have the details now, or be ready to provide them while the RFC is open, but your questions will help us to write better RFCs over time and to know what we need to answer before we finish a project.
  • Suggesting what would make a problem worth solving.
  • Suggesting better solutions, or enhancing with your ideas about how to create more value.

Votes and vetoes

We saw some engagement that framed RFCs as the means to “veto” an idea. Clearly, that reflects the guidance I provided in “How to write good comments?” However, RFCs need to reflect “a bias for action”: here’s a problem; what can we do together to find a solution? While we’re utilizing some democratic methods to explore those topics, the ultimate decision lies with the author, not a vote from the community. To clarify our intent, RFC is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

Prioritization

In recent discussion, I asserted that “priorities are out of scope”. While the RFC problem statement should convey value (and hence a sense of priority), meaningful discussion of priorities (plural) demands a discussion of relative trade-offs. For the RFCs, we’re not ready to have that conversation when we haven’t yet made enough work visible to discuss sequencing. Even when we achieve greater transparency as more projects get an RFC, there are still trade-offs that remain internal to Atlassian. Therefore, we assert that RFCs should be treated as independent of each other and that relative prioritization is “out of scope” in the RFC threads. Please keep the RFC comments to negotiating toward the most valuable thing to build.

We can have relative prioritization discussions based on other sources, in other categories. For example, it is valid to bring up the prioritization of our Cloud Roadmap or Forge Roadmap. In time, we hope the RFC process is so widely adopted that every RFC lands on a roadmap, and that we can have a discussion of priorities about the roadmap.

Proposed revision: How to write good comments?

Good comments focus on identifying serious flaws and providing constructive feedback. Participation should follow the developer community participation guidelines . We especially call out the need to keep conversation welcoming and safe by commenting on the idea not the people (especially the author). Keep it tidy by keeping on topic and respond at the appropriate level in the thread. If you are going to comment about the RFC itself, respond to the top level. Please, keep comments constructive to help empower the community. Even serious flaws should be explained in ways that help drive better outcomes for the community.

While the RFC problem statement should convey value (and hence a sense of priority), meaningful discussion of priorities (plural) demands a discussion of relative trade-offs. RFCs should be treated as independent of each other and that relative prioritization is “out of scope” in the RFC threads. Please keep the RFC comments to negotiating toward the most valuable thing to build.

  • Ask for more clarification in areas you need to understand better. We might not have the details now, or be ready to provide them while the RFC is open, but your questions will help us to write better RFCs over time and to know what we need to answer before we finish a project.
  • Suggest what would make a problem worth solving.
  • Suggest better solutions, or enhancing with your ideas about how to create more value.
7 Likes
21

How about a repo with a file per RFC in Bitbucket? Pull requests for changes. Cant get more transparent than that. Plus supports markdown.

22

This approach wouldn’t result in a notification being triggered to thread participants. Maybe worth changing this to unlock a thread and have the author post an update then re-lock?

1 Like
23

On schedule this time, I’m closing RFC-1. With 963 views as of today, we again nearly broke 1000! There were 75 likes and 10 commenters contributing 22 comments. With this “meta RFC” and some real topics, we learned a lot about how Atlassian can better leverage the developer community in better planning. I’ll be preparing a resolution to this topic over the next couple weeks. I need time to digest all the feedback but I’m certain that we’ll want to make a revision of this practice. Please stay tuned for resolution or before 24 March 2023.

2 Likes
24
25
26

What did we hear?

The RFC itself is very “meta”: it attempts to model what it describes. As such, it would be awkward to separate this resolution from the experience across all the RFCs so far.

  • On the whole, we heard these RFCs are needed and useful. Indeed, an immediate question was how to get wide-spread participation, a la, “how will the Atlassian team know when to raise an RFC?”
  • Hopes that governance would create more transparency. Even with this published RFC live, we have had some community threads that maybe should have been RFCs.
  • So far, RFCs have been shallow on explaining the paths not taken; we’re not conveying “the chain of thought that led to the proposed solution”.
  • Tracking changes to RFCs. The community needs to know when things change and quickly catch up.

As a community, I ask that you support our effort to spread this practice and that you keep prompting for RFCs.

What did we change?

While the RFCs were in discussion, we wrote additional internal guidance to supplement this public document. We recognize some flaws remain and simply ask that you do what feels natural. We will make improvements but we need more experience to drive appropriate prioritization.

What is coming next?

Even with these known but not serious flaws, we will continue with the RFC process. Having this RFC category in the community is better than not. We would like to have experience from 10 or more RFCs before we look at both process and technical improvements. If we don’t hit 10+ RFCs by June, we need to have a hard look at why. So, either way, please expect an RFC-on-RFC revision in June.

3 Likes
27