API description checklist compliance review

[anthorange]

Problem description
This issue is based on the Camara Marketing “Checklist for API description review”:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

The Know Your Customer Fill In API page reviewed:
https://camaraproject.org/know-your-customer-fill-in/

The page has checklist compliance gaps for:

• API Description (the image is too small / technical)
• Use Cases (text format / missing GSMA Use Case Library links)
• Benefits (text format)
• Sub Project Wiki (incorrect prefix)

Expected action
Please update the Know Your Customer Fill In API documentation page so it matches the checklist by applying the following corrections:

1. API Description

• The image is currently a technical flow chart that is hard to read (too small). To meet the checklist requirement, replace or redesign it so that it clearly illustrates a typical developer-facing use-case workflow and highlights the API value.

2. Use Cases

• Use case name should be in bold (none of them are).
• Add GSMA links that match appropriate use cases: https://www.gsma.com/solutions-and-impact/gsma-open-gateway/gsma-open-gateway-resources/?category=use-cases. I couldn't find any relevant use case for this API so I'm linking to the main use cases page.

3. Benefits

• Benefit name should be in bold (none of them are).

4. Sub Project Wiki

• The correct prefix is "Sub Project Wiki:" (current prefix: "SubProject Wiki:")

Additional context
Checklist reference:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

Reviewed page export:
https://camaraproject.org/know-your-customer-fill-in/

[MarkusKuemmerle]

Hello,

the CAMARA outreach team is currently reviewing all the API descriptions to improve it and make it attractive for customers and developers. There is some confusion how to handle and solve the findings. I would like to give the following recommendations:

• Findings in the text of API description, Use Cases, Benefits: These should be solved by the Sub Project, changes should be documented in the API description Wiki page, and then the Sub Project should open an issue in the Marketing repo to change the website. This follows the defined process description to change the website.

• Findings in the visuals: The Sub Project should give instructions to improve the visuals following the criterias defined in the checklist. The instructions also can be included in the wiki page and addressed to the outreach team by issue in the Marketing repo. We plan to ask the LF creative team to generate new visuals for us based on these instructions.

• Findings on the right column (with all the links): Reviewers should put these findings in the review xls and not in the issue. Sub Projects cannot solve it. The CAMARA outreach team is taking the findings from the xls and is changing the website.

So please work on 1. and 2. and 3. and ignore 4. in the first comment above.

Hope that helps, Markus

[ToshiWakayama-KDDI]

By my understanding of the above comments, what we have to do is:

a. API Description (the image is too small / technical)
b. Use Cases (Use case name should be in bold)
c. Use Cases (missing GSMA Use Case Library links)
d. Benefits (Benefit name should be in bold)

[ToshiWakayama-KDDI]

Hi all,

I have received a omplete proposal from Alberto (TEF), including the drawing. (Many thanks, @albertoramosmonagas )

I have put the proposal to the wiki page, so, please review the proposed description and give your comments / change proposals. (You can add comments below in the page.)

The link is:
https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/137592951/KnowYourCustomerFill-in+API+description

The existing content is still existing there and the proposed new content is located below it.

Thanks.