Redesign organization README for better discoverability #23

hdamker · 2026-01-19T17:41:21Z

What type of PR is this?

enhancement

What this PR does / why we need it:

Replaces the current release-table-focused organization README with a user-persona navigation guide.

Key changes:

Removes 450-line HTML API table (information now maintained in API Portfolio)
Adds "Where do I start?" navigation for different user types
Links to authoritative sources (API Portfolio, Wiki, Governance docs)
Adds news banner for project announcements using GitHub alert syntax

Benefits:

Easier to maintain (no manual table updates per release)
Directs users to the right resources based on their intent
Concise and scannable

Which issue(s) this PR fixes:

Fixes camaraproject/Governance#211

Special notes for reviewers:

Request review from Marketing WG for content/messaging
Request review from TSC for approval of approach change
Compare with current README to verify all key links preserved

Additional documentation

This section can be blank.

Replace the release-table-focused README with a user-persona navigation guide that directs visitors to the right resources based on their intent. Key changes: - Remove 450-line HTML API table (now in API Portfolio) - Add "Where do I start?" navigation for different user types - Link to authoritative sources (API Portfolio, Wiki, Governance) - Add news banner for project announcements Fixes camaraproject/Governance#211

bigludo7

Thanks @hdamker
Look good for me - just a small comment for your consideration.

bigludo7 · 2026-01-20T09:53:02Z

profile/README.md

+- **[CAMARA API Design Guide](https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md)** (Commonalities)
+- **[Common API design and interoperability guidelines](https://github.com/camaraproject/Commonalities)** (Commonalities)
+
+These documents are maintained by the respective working groups and apply across APIs.


Very small comment but we haven't document called CAMARA Security and Authentication Profiles and Common API design and interoperability guidelines but instead we target the project git hub.

Maybe for ICM is worth to refer to Security and Interoperability Profile on the one hand and on other hand to Access and User Consent Management

Please review updates in 78988d0

Thanks @hdamker

Kevsy · 2026-01-20T12:02:00Z

profile/README.md

-Visit our [Wiki](https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/overview?mode=global) for more details about the [Fall25 meta-release](https://lf-camaraproject.atlassian.net/wiki/x/FQApAg) and the [Release Management in CAMARA](https://lf-camaraproject.atlassian.net/wiki/x/US7e). Please note that there are more APIs in work - see the complete list of [Sandbox API Repositories](https://github.com/search?q=topic%3Asandbox-api-repository+org%3Acamaraproject&type=Repositories) which follows also below.
+# CAMARA Project
+
+CAMARA is a global open-source project that enables the exposure of network capabilities through standardized APIs. The project brings together operators, vendors, and the broader ecosystem to define, evolve, and release interoperable APIs.


Suggested change

CAMARA is a global open-source project that enables the exposure of network capabilities through standardized APIs. The project brings together operators, vendors, and the broader ecosystem to define, evolve, and release interoperable APIs.

CAMARA is a global open-source project that enables the exposure of network capabilities and information through standardized APIs. The project brings together network operators, equipment vendors, and the broader ecosystem to define, evolve, and release interoperable APIs.

@Kevsy To avoid "definition creep" I have reverted the start of the README in 7cf736a back to the previous "Welcome" and pointers to the authoritative project definitions on the website and in the ProjectCharter, (just with the website before the wiki). Here is not the place to refine the project definition ;-)

Kevsy · 2026-01-20T12:29:42Z

profile/README.md

+
+---
+
+## Where do I start?


Suggested change

## Where do I start?

## 📍 Where do I start?

@Kevsy Adding emojis to every section heading might dilute the effect of 👉 for key call-to-action links (3 times) and make the page busier. Nevertheless the I created the alternative page with the emojis (slightly different selection) to get feedback from the community which version is preferred, see comment below.

Kevsy · 2026-01-20T12:29:46Z

profile/README.md

+
+---
+
+### I want to explore CAMARA APIs


Suggested change

### I want to explore CAMARA APIs

### 🔎 I want to explore CAMARA APIs

Kevsy · 2026-01-20T12:29:51Z

profile/README.md

+
+---
+
+### I want to use or implement a specific API


Suggested change

### I want to use or implement a specific API

### 🚀 I want to use or implement a specific API

Kevsy · 2026-01-20T12:29:55Z

profile/README.md

+If you already know which API you are interested in:
+
+Start with the **API Portfolio** and select the API (for implementation, use the latest meta-release, currently **Fall25**), then follow the link to the **API repository release** on GitHub, read the repository README and API documentation, and review the published OpenAPI and test specifications.
+


If I want to use an API, I will likely be looking for live implementations - so we can add the link to the GSMA map: https://open-gateway.gsma.com/map

Added in 78988d0

Kevsy · 2026-01-20T12:29:59Z

profile/README.md

+
+---
+
+### I want to participate in the CAMARA community


Suggested change

### I want to participate in the CAMARA community

### 👋 I want to participate in the CAMARA community

Kevsy · 2026-01-20T12:30:02Z

profile/README.md

+
+---
+
+### I want to contribute to an API or specification


Suggested change

### I want to contribute to an API or specification

### 👷 I want to contribute to an API or specification

Kevsy · 2026-01-20T12:30:05Z

profile/README.md

+
+---
+
+### I maintain an API or drive releases


Suggested change

### I maintain an API or drive releases

### 🏁 I maintain an API or drive releases

Kevsy · 2026-01-20T12:30:09Z

profile/README.md

+
+---
+
+### Looking for something else?


Suggested change

### Looking for something else?

### 🔭 Looking for something else?

diegogonmar · 2026-01-20T15:17:06Z

profile/README.md

+- **[CAMARA API Design Guide](https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md)** (Commonalities)
+- **[Common API design and interoperability guidelines](https://github.com/camaraproject/Commonalities)** (Commonalities)
+
+These documents are maintained by the respective working groups and apply across APIs.


Maybe for ICM is worth to refer to Security and Interoperability Profile on the one hand and on other hand to Access and User Consent Management

diegogonmar · 2026-01-20T15:20:09Z

profile/README.md

+- **[CAMARA API Design Guide](https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md)** (Commonalities)
+- **[Common API design and interoperability guidelines](https://github.com/camaraproject/Commonalities)** (Commonalities)
+
+These documents are maintained by the respective working groups and apply across APIs.


Another comment is that in these ICM and Commonalities references we do not indicate that are also related to a certain meta-releases (link to github will go to latest release). Maybe it's good to mention, same as in the portfolio, that the version matching the meta-release of the API to be implemented should be selected

diegogonmar · 2026-01-20T15:23:26Z

profile/README.md

+
+- **[Contributing Guidelines](https://github.com/camaraproject/Governance/blob/main/CONTRIBUTING.md)** (project-wide contribution process), **[Project Charter](https://github.com/camaraproject/Governance/blob/main/ProjectCharter.md)** and **[Project Structure and Roles](https://github.com/camaraproject/Governance/blob/main/ProjectStructureAndRoles.md)**
+- **[CAMARA API Design Guide](https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md)** (Commonalities)
+- **[Propose a new API](https://github.com/camaraproject/Governance/blob/main/documentation/API-Onboarding-and-Lifecycle.md)** (API onboarding and lifecycle)


What about a section for contribution to ICM indicated as applicable if contributing to Security, Identity or Consent topics?

- Fix ICM document references: use actual document names (Security and Interoperability Profile, Access and User Consent Management) - Fix Commonalities references: link to specific documents (API Design Guide, API Testing Guidelines) - Add note about using meta-release-matching document versions - Add GSMA Open Gateway operator map link for live implementations - Add ICM repository to contribution section - Simplify Commonalities reference in contribution section

Address PR review feedback by reverting to the proven upstream-style introduction that points to authoritative sources (Website, Wiki, Governance, Project Charter) instead of defining CAMARA inline. This avoids "definition creep" and keeps the intro concise.

diegogonmar

Thanks for addressing my comments @hdamker. LGTM

hdamker · 2026-01-21T14:37:58Z

Based on @Kevsy's suggestions I have created an alternative version of the resulting README.md with emojis. Please have a look on the two variants with and without emojis and leave your comment which version you prefer.

A compromise as third option could be to keep just 📍 on "Where do I start?" as the main navigation anchor and skip the emojis on subsections.

bigludo7 · 2026-01-21T15:01:14Z

Preference for the Emoji version 🚀

diegogonmar · 2026-01-21T18:51:57Z

I prefer the emoji version

hdamker requested a review from a team as a code owner January 19, 2026 17:41

hdamker requested review from a team January 19, 2026 20:38

bigludo7 reviewed Jan 20, 2026

View reviewed changes

Kevsy reviewed Jan 20, 2026

View reviewed changes

profile/README.md

---

### Looking for something else?

Copy link

Kevsy Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

### Looking for something else?

### 🔭 Looking for something else?

diegogonmar reviewed Jan 20, 2026

View reviewed changes

hdamker added 2 commits January 21, 2026 13:55

diegogonmar approved these changes Jan 21, 2026

View reviewed changes

Add emoji variant of README for community feedback

e44e9fc

	CAMARA is a global open-source project that enables the exposure of network capabilities through standardized APIs. The project brings together operators, vendors, and the broader ecosystem to define, evolve, and release interoperable APIs.
	CAMARA is a global open-source project that enables the exposure of network capabilities and information through standardized APIs. The project brings together network operators, equipment vendors, and the broader ecosystem to define, evolve, and release interoperable APIs.

	### I want to explore CAMARA APIs
	### 🔎 I want to explore CAMARA APIs

	### I want to use or implement a specific API
	### 🚀 I want to use or implement a specific API

		If you already know which API you are interested in:

		Start with the API Portfolio and select the API (for implementation, use the latest meta-release, currently Fall25), then follow the link to the API repository release on GitHub, read the repository README and API documentation, and review the published OpenAPI and test specifications.

	### I want to participate in the CAMARA community
	### 👋 I want to participate in the CAMARA community

	### I want to contribute to an API or specification
	### 👷 I want to contribute to an API or specification

	### I maintain an API or drive releases
	### 🏁 I maintain an API or drive releases

	### Looking for something else?
	### 🔭 Looking for something else?

Redesign organization README for better discoverability #23

Are you sure you want to change the base?

Redesign organization README for better discoverability #23

Conversation

hdamker commented Jan 19, 2026

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Special notes for reviewers:

Additional documentation

Uh oh!

bigludo7 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

diegogonmar left a comment

Choose a reason for hiding this comment

Uh oh!

hdamker commented Jan 21, 2026

Uh oh!

bigludo7 commented Jan 21, 2026

Uh oh!

diegogonmar commented Jan 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants