Feature Context Docs: a pattern for transparent collaboration in open orgs

Our Mission
, , ,
1

How we can make our decision-making visible, explainable, and reusable

To meaningfully collaborate, both core and external contributors need more than open code and design—they need context. This post proposes a lightweight but powerful way to log the thinking behind our product decisions, tradeoffs, and implementation paths. It’s one of the first improvements we’ll be experimenting with starting in May to make building in public more productive, collaborative, and sustainable.

:brain: Observation

It’s surprisingly easy to open the code and still keep the thinking closed.

Even for experienced contributors, it can be difficult to engage meaningfully when product rationale and decisions are buried across Discord threads or scattered chats. Following outcomes becomes easier than understanding the “why”—and that dynamic quietly recreates top-down hierarchies, even in open-source settings.

:bulb: A helpful analogy

The products and services we create are like software.

But our culture—how we solve problems, communicate, share knowledge, and make decisions—is more like hardware.
It sets the constraints and capabilities of everything we build on top.

To truly build in an open-source way—beyond Status, at the wider IFT and public level—we need to keep both the software and the “hardware silicon” of culture open. That means:

  • Code and protocols → open, auditable, forkable
  • Decision-making and culture → visible, explainable, reusable

Without both, we risk creating barriers to contribution—even when the code is public. Making our culture of decision-making transparent turns open code into an open project.

:wrench: A proposal: Feature Context Doc

I’m suggesting we start maintaining a simple Feature Context Doc for each epic or problem space. These live in Notion (or any open wiki with inline comments) and are:

  • Created during epic decomposition
  • Co-authored by developers, design, QA, and tech writers
  • Updated as decisions evolve
  • Linked from the GitHub Epic
  • Open whenever possible

:mag: Important note: This is not a product brief. The brief is a high-level feature request from a product lead, grounded in business or user needs.
The Feature Context Doc picks up from there—capturing the deeper design, tech, and implementation context needed to execute well.

:jigsaw: Suggested structure

This isn’t rigid—but from experience, these sections help everyone stay aligned:

1. Current state
What exists today? What works, what doesn’t?
Known issues, UX gaps, or QA insights

2. Reusability
What parts of the frontend/backend can be reused?
What needs redesign or cleanup?

3. Dependencies
What APIs, protocols, or third-party tools are involved?
What tradeoffs exist between alternatives?

4. Agreed compromises
Where are we intentionally cutting corners to deliver value faster?
What risks are we accepting?

5. Success metrics
How will we know this worked?
Direct or indirect indicators (conversion, feedback, reduced bug volume, etc.)

6. Traceability
Links to Discord threads, specs, Figma, research, user input, etc.
This helps people catch up without needing a deep Discord archaeology session.

:speaking_head: To be clear: this isn’t about replacing Discord discussions.
The goal is to complement them—by giving key decisions and insights a structured, searchable home. That way, even deep async collaboration stays aligned, and contributors don’t have to reverse-engineer decisions from scattered threads.

:white_check_mark: Benefits

  • Faster onboarding to active participation for internal and external contributors
  • Better async work with fewer misunderstandings
  • More autonomy across product, design, and engineering
  • Less duplicated effort and more durable team knowledge
  • Documentation of rationale, not just implementation

:thread: TL;DR

  • Open code isn’t enough—we also need to open up decision-making
  • Feature Context Docs are structured, evolving documents created after a team receives a brief from the product lead
  • They include: current state, reuse, dependencies, compromises, metrics, and links to decision history
  • These docs improve onboarding, reduce ambiguity, and make async collaboration easier
  • This is one of the small improvements we’ll start experimenting with in May
  • Happy to share a template—curious what others think and how you approach this

Thanks for reading. Sharing this based on what I’ve seen across Status Mobile, Desktop, Shell, and Keycard workflows—shaped by the evolution we’ve made as one team and one org over the past year. Feedback welcome, and I’d love to hear how others are making thinking visible in open work.

:hammer_and_wrench: Update (based on @Tetiana feedback):
Thanks to some insightful discussion, I’ve clarified a few key points:

  • Feature Context Docs are not formal specs—they’re lightweight, living references meant to reduce noise and help everyone stay in sync.
  • Planning one milestone ahead is essential for this to work well. We’re already moving in that direction, and I see this as part of that evolution.

Appreciate the feedback—it helped refine the intent and fill in blind spots. Let’s keep shaping this together

2 Likes
2

Thank you, @alisher , for this post — I fully agree with all the points you’ve raised.

Just to add my perspective: we’ve already discussed similar topics in relation to user flow descriptions, feature definitions, user stories, and the definition of done. My two cents — if we want to maintain a solid level of quality, properly document our decisions, and truly embrace the open-source approach (which I completely support), we need to slow down and plan at least one milestone ahead.

For example, if we’re in milestone 2.34, the feature discussions for 2.35 should already be happening. Discussions, design, and proper documentation take time — and that’s the main issue I see right now. Expecting to have a product brief and deliver everything within the same milestone is unrealistic. If that remains the expectation, things will stay hectic.

Another major point: we don’t have a clearly responsible person whose main task is to describe features in a consistent and structured way. That’s a full-time role. QA and devs can absolutely support — ask questions, suggest improvements — but it’s not sustainable to expect engineers, already overloaded with work, to produce detailed, cross-repo, client-facing epic descriptions.

To summarize, I see two core problems:

  1. This process is not compatible with “fast” development — it requires early planning.

  2. There’s no dedicated role accountable for documenting epics in a structured and consistent way across repos and clients.

1 Like
3

Thank you so much for raising these important points, @Tetiana — especially around planning cadence and structured documentation. I really appreciate you surfacing the spots I didn’t address clearly in the original post. This kind of proactive reflection is exactly the kind of collaboration we need to evolve together.

1.Planning ahead:
Yes, I fully agree that we need to start feature planning at least one milestone in advance. From my perspective, planning should serve productive and healthy development, not dictate it—and it should adapt flexibly to product needs. We’ve already taken some first steps in this direction, and I believe we’ll start seeing positive effects pretty soon.

2.On documentation ownership and structure:
I see the Feature Context Doc not as a formal, detailed spec or a client-facing epic—but more like a living reference point for the team. It holds the latest decisions, tradeoffs, agreements, and links—just enough to help anyone jump into context quickly without having to do Discord archaeology or arrange new meetings.

Maintaining it shouldn’t be a formal responsibility—it should become a culture click. When we reach an agreement, have a shared insight, or uncover valuable context in a meeting or discussion, we just copy it in. The same way we’re now building a habit of using the Inbox mid-sprint. (Just last week, a QA request landed in chat, I started to follow up manually, and Shivek gently reminded me: “Shouldn’t this go to the inbox?” And of course—it did.)

That’s how practice becomes habit and habit becomes culture: when people begin to reference it, support it, and reinforce it—because they see how it improves clarity, lowers stress, and saves time.

I see the Feature Context Doc as part of that same direction—a small, low-friction team–wide experiment to help us release some of the energy currently lost to repeating ourselves or trying to reconstruct decision threads and extract valuable information from outdated replies.

I’ll update the post soon to reflect the concerns you raised and make sure the framing removes those blind spots. Thanks again :raised_hands:

1 Like
4

Thank you for this post @alisher , this is a very important topic and it dovetails perfectly into the subjects we’ve been discussing over the past few months. I’m really happy to see you open this conversation to a public post, thank you.

You make a number of point that I agree with very strongly.

:100: :clap:

:100: :clap:

Our Processes

I believe that product briefs should also be public, or at very least a subset of product briefs. We need to make clear publicly what the process for going from feature request to implementation is. Which ties nicely into your point of “Decision-making and culture → visible”. As a community member I’d want to know how does an idea go from my feature request to being in the app.

As you know I performed some research on this subject in an attempt to gather an understanding of what each team within Status find important, please see the here: Status App - Feature Lifecycle and here Feature Lifecycle - Status Teams Feedback Analysis.

One of the key outcomes was identifying a common need for a “Requirements Document”. In your view, is the Feature Context Doc a precursor to that, or a replacement, or another distinct layer of shared understanding, or even a sub-set / super-set of that?

The Struggle for an Open Wiki

The question of where our wiki should live I feel is not resolved. Notion is good for user convenience however it is proprietary and closed source, we have no control over what Notion decides to do with our data or what access Notion will allow us to have in the future. I do not like Notion particularly for our public facing engagement.

I’m still very much in support of a WikiMedia Wiki like Logos has, and this was my main push in the below post.

And as a compromise I created this github based wiki Status App - Wiki. But I don’t think that a Github wiki is a very featureful one, there are too many features not available in a Github wiki, it is basically loosely knitted markdown files with a git version control. And it doesn’t have inline comments!

“open wiki with inline comments”

I hear this, this is something I’ve been working on.

I’ve been experimenting with MediaWiki’s InlineComments extension with a local installation of a template wiki as a possible path forward. This plug in is very featureful and it combines what we want from an OS wiki with the collaborative features we’re used to from tools like Notion. See the video below from the wiki extension page:

Outro

I’d love to explore how your Feature Context Doc format, Feature Requirements Document, our ADR template, and the idea of a shared wiki might come together into a coherent documentation ecosystem. Something lightweight but expressive, where decisions, motivations, requirements, and implementation context are all visible, traceable, and remixable.

Thanks again for kicking this off in public. Looking forward to seeing where it goes and being part of it.

1 Like
5

Thanks Sam—love this connection to the Requirements-First Development flow. I agree that Feature Context Docs can be a great way to capture and structure the shared understanding that comes out of the 3 Amigos conversations.

One small nuance I’d offer for discussion:
In my view, user stories often come after the deeper 3 Amigos exploration, not before. While we might sketch rough ideas early on, the more grounded user stories usually crystallize once we’ve looked at feasibility and constraints across design/dev/QA—not just from the brief alone.

Brief should serve as a high-level request backed by business and user needs, and feasible user stories are an answer to this request—not the request itself.

That’s why I imagined the Feature Context Doc holding links to user stories, but not trying to replace them or force them in too early. For me, it’s a shared reference that captures:

  • Current state
  • Prior context
  • Decisions and tradeoffs
  • Feasibility notes
  • External dependencies
  • … and yes, eventually, what we agreed the user should receive

Happy to evolve the structure or co-create a version of the doc that fits more tightly into the Bambi Steps. I think there’s a real opportunity here to connect process with context in a way that’s light but powerful.

6

@samuel, being honest—I love Notion. Its user-centric UX is outstanding, and it’s been my go-to workspace for years across personal and professional projects. I consider myself a power user.

That said, I share your concerns—and I think they’re valid. Notion’s current stance raises a few red flags when viewed through the lens of privacy, open-source principles, and user data sovereignty:

Issues with Notion:

  1. Not open-source – The entire platform is proprietary, which limits transparency and community auditability.
    Notion Privacy Policy
  2. No end-to-end encryption (E2EE) – Your data is encrypted at rest and in transit, but Notion can technically access your content.
    Comparitech analysis
  3. Data collection & sharing – Notion collects device info, usage behavior, and personal data, some of which may be shared with third-party vendors.
    PolymerHQ breakdown
  4. Limited self-hosting or data control – All data lives on Notion’s infrastructure with no local-first option.

Exploring better-aligned alternatives

If we, as an organization, choose to prioritize tools that reflect our values—privacy, transparency, self-sovereignty—then I’d be more than willing to leave my comfort zone and embrace a new tool.

Anytype, in particular, looks like a promising alternative that might align better than Wikimedia:

  • Open-source
  • End-to-end encrypted
  • Local-first with optional sync
  • Designed for trustless, user-owned knowledge systems
    anytype.io

It feels like a more modern, value-aligned reimagining of what Notion could be—without the compromises.

1 Like
7

Anytype! :tada: I can get behind that. I am a supporter and user of AnyType. I do a lot of personal planning work and creative projects in Anytype, I absolutely love it. I even comment in their forums from time to time, they are very welcoming and helpful.

They are an open source organisation and they support other open source projects. See this link of one of my interactions with them What theme are you using in this forum? - Talk - Anytype Community .

8

Thanks for this post, Alisher. The proposed Feature Context Doc would be a solid step forward!

Feature Context Doc

The suggestions are reasonable, but as Samuel noted, we already have docs to maintain, or plan to start using more, so it’s important to keep expectations for this one lightweight, especially at first.

This proposal reminded me about how organizations learn at their own pace. For example, we haven’t even fully executed on user stories yet, and we’re already discussing how to connect them with more involved processes. Which raises an important question: what’s the most critical change we want to see in our delivery processes right now? Process focus is just as important, if not more, than product focus.

It might also be helpful to define success criteria processes, not just features. If something isn’t working, we should be able to recognize that early and adapt, fail fast.

On the topic of documentation ownership: in my experience, when a document is everyone’s responsibility, it ends up being no one’s, and that often leads to it going stale. Ownership might sound a bit heavy. To me, it’s more about assigning facilitator(s) who can ensure the doc stays current, without being the sole maintainers. At the same time, it should stay open to collaboration, without any bureaucratic barriers.

Release milestones and releases

I’d like to see Status evolving in how we ship software, so I’m going to share a few of my thoughts here, but I think it’s not really the focus of the original post.

The current approach of using numbered releases is rigid and creates unnecessary overhead in communication, planning, and execution. As soon as we start assigning features to specific releases, we’re forced to predict outcomes, something that rarely works well in software development.

We have plenty of evidence pointing to issues in our current delivery process:

  • We’ve consistently delayed releases since 2.30.0. Not because we’re slow, but also because the deadlines were off.
  • We frequently change release branch cut dates and waste time in discussions with leads about when to do it.
  • There’s frequent scope negotiation.
  • We resort to urgent workarounds just to meet deadlines.
  • We deal with complex coordination across IFT projects.
  • We face marketing coordination challenges.
  • We ship suboptimal UX. For example in Mobile: in 2.33, many Keycard improvements were released, but important UI/UX fixes followed just after the release and up to this date, we haven’t yet being able to release because status-mobile develop branch is not releasable.

Features don’t need to be analyzed one milestone in advance. We can assess them when the time is right, when we have the capacity, and when they align with our goals. But at the same time, it shouldn’t become a chaotic process as we’ve recently experienced.

Analysis is sometimes the most resource-intensive part of delivery, and like any step, doing it means not doing something else. That tradeoff needs to be clear to everyone. If we want a successful 3-amigos process, we have work to do here. Developers will be contributing beyond just writing code. They won’t simply pick up “ready for dev” issues. It’s a positive shift, but it also increases lead time, which some stakeholders may not fully understand or value yet.

Back in Aug/2024, Shivek and I tried to align with everyone on a more flexible release model: ship when we’re ready, avoid deadlines. Unfortunately, we’ve moved away from that approach. Status development teams should strive much harder to keep development branches releasable.

I see a familiar pattern in Status: when teams face uncertainty, they often respond by trying to create more certainty within their bubble of control. It’s not bad per se, but it’s worth reflecting on.

About Notion usage

A discussion for another post :slight_smile:

I’ve noticed that every time we bring up Notion, the conversation quickly shifts to alternatives. Probably because, personally and as an organization, we’re not really proud of this choice. Notion is problematic.

Given the impact across Status, this is something that should be raised with all of leadership so a decision can be made. The usual counter-argument is the cost of migration and time for everybody to adapt, and then the discussion fades away, just to be brought up two months later. Personal preferences often get in the way, which is understandable. There’s also the problem of losing history, again another reason to steer away from Notion’s closed nature.

I believe we could migrate fairly quickly once we commit, starting with the most-used Notion pages to see immediate benefits. It’s better to stay true to our principles and absorb the cost sooner rather than later, before the problem gets even bigger.

1 Like
9

Thanks so much for joining the thread and sharing your perspective, @icaro . :raised_hands: Your thoughts are incredibly valuable and pushed me to reflect more deeply on my motivations behind this proposal. Also, great to see you jumping into public conversations here—congrats on your first Discuss post!

Completely agree—process focus is just as essential as product focus.
From my point of view, one of the most energy-draining issues I’ve seen lately is chaotic knowledge flow and scattered decision-making. Things get decided in one call or thread and never surface again, leading to shifting focus, redundant questions, and slow follow-through. That’s the pain I’m trying to address first.

Totally aligned—and this is actually part of the Feature Context Doc template. We need a way to reflect not just on whether a feature worked, but whether the way we shipped it worked too.

I don’t believe in assigning ownership and setup processes just for the sake of it—but I do believe in the power of seeing a practice as profitable. When people recognize that keeping a doc current saves time, avoids rework, prevents duplicate conversations, and makes design/dev/QAs smoother, someone naturally steps up to facilitate relevant parts. That’s already happening in small ways—like when Shivek redirected something into the inbox instead of chat. For now, I see the value personally, so I’m keeping it updated. If others start seeing the same value, it’ll take root.

I hear you. What I’m suggesting is not rigid planning, but early visibility. If a feature is at least present in a draft roadmap—something lightweight and transparent—then people can choose to explore it when there’s time and space. That’s very different from something suddenly popping up with urgency and little prep. Visibility gives us breathing room.

Yes—this is where I think we’re evolving from a corporate “Junior/Mid/Senior” hierarchy to a decentralized builder culture. In that model, “Why” always comes before “How,” and that’s true for everyone involved. It’s a big mindset shift, and I agree it needs to be supported with shared context, trust, and space to think—especially for the 3 Amigos to work well.

Grateful for your thoughts, and for reminding us that process improvement is a cultural evolution, not just a checklist. Would love to keep evolving this together, especially as we experiment with Feature Context Docs in real workflows. Let’s see what actually sticks and helps.

1 Like