QoD 0.9 - inline documentation problems

[murthygorty]

Problem description
Hello, I noticed that we moved to inline documentation. This poses a problem for stakeholders/Product folks or even Devs who just to understand the API quickly without using a tool.
Also, I believe this doesn't meet the check-list requirement for documentation: https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/API-Readiness-Checklist.md

Comparatively, 0.8.1 is so much nicer to consume:
https://github.com/camaraproject/QualityOnDemand/blob/release-0.8.1/documentation/API_documentation/QoD_API.md

Expected action
Expose documentation that is easy to consume like 0.8.1

Additional context
<none - see description>

[murthygorty]

cc: @gmuratk

[patrice-conil]

Hi @murthygorty,
Have you tried swagger online editor ?
As a developer, I prefer all-in-one specs/docs over separate docs because separate always introduce consistency issues.

[murthygorty]

Hi Patrice, as a developer of the spec, there is a advantage as you say.
In my view, we should prioritize the experience for the audience
--- product mgrs looking to understand the functionality and capabilities.
--- developers who are consuming; we will use swagger for the spec only after we understand to he overview.

Also, if you look at the documentation created for 0.8.1 (above OP link), would we be able to create such rich documentation online?

[patrice-conil]

Hi @murthygorty,
Sorry, I was not clear.
I meant as a consumer developer...not as developper of the spec.
I always doubt the accuracy/consistency when I find multiple documents because I know it's hard to maintain.
And yes, we have already included the Markdown documentation in the oas file...so we could include more.

[patrice-conil]

Besides, I always generate the models and the API from the OAS to be sure not to miss anything.

[murthygorty]

ahaa, thanks @patrice-conil - so, if I understood you correctly, are you suggesting that

1. API Developers include all the documentation, markdown (pictures too?) in OAS.
2. before an API is released a tool is run to generate a non-Dev consumable documentation as part of release checklist?

if so, that is perfectly fine, imo.

Without #2 above, I am sorry I cannot agree. CAMARA consumption cannot be for developers only. CAMARA releasechecklist we have is really good and caters to the appropriate audience (including Technical Product Managers in customer organizations who need to create requirements towards Customer Development teams).

If we agree on #1 and #2 above, we still need to fix this issue so that there is a document that is part if 0.9 release :-), don't you agree?
cc: @hdamker @gmuratk

[patrice-conil]

Hi @murthygorty,
I was just suggesting (1)...but if you really need (2), which I can understand, I don't feel competent to answer.

[jlurien]

For (2) it would make sense to explore some way to generate a HTML formatted version of the yaml spec, with tools such as redocly/redoc, and provide that output as part of the project. This is something transversal to all WGs.

[murthygorty]

all above sounds good @patrice-conil , @jlurien .
until the tooling is in place, I highly recommend that do what we did for 0.8.1. Basically, follow the current guidelines and work on improving the guidelines..
This is especially true for QoD API because, this has been the best documentation that we (TMUS) have been referring to as the example to follow :-)

As tooling parts are figured out, may be work with commonalities project to change the check-list for API readiness, appropriately?

thank you.
cc: @hdamker @gmuratk

[jlurien]

I don't think we should go back to what we did in 0.8.x, as that implies duplicating the effort to maintain doc in two different places. If the problem is to provide a non-dev friendly version of the yaml spec, there are some simple ways to provide that in the short term, until we decide to build a proper web hosting of our html versions of the APIs.

For example we could add the URL to the API version (raw) as parameter to

https://redocly.github.io/redoc/?url=<url>&nocors

and use that in the links in the README.md, as in

Status and released versions

...

• Release 0.9.0 of the API is available within the release-0.9.0 branch:
  • API definition with inline documentation
  • For changes see CHANGELOG.md
• The previous version v0.8.1 of the QoD API is available within the release-0.8.1 branch.
  • API definition with inline documentation for 0.8.1
    ...

To avoid external dependencies, another option could be to build the html doc with some Github actions host the files in Github Pages. Similar to this

[gmuratk]

Shouldn't we take this discussion to the Commonalities subproject to get an explicit guideline for all subprojects?
@shilpa-padgaonkar

[murthygorty]

fwiw,

1. I am good with @jlurien's proposals because the non-Devs will still be able to see the documentation, by clicking a link
2. This documentation has to match the documentation template from Commonalities subproject. Else it is a bug.
3. a tag/version shouldn't be released with a non-working documentation page (link)

[murthygorty]

Thinking about some more, I completely agree with @gmuratk .

• is the current 0.9.1 compliant with commonalities? If yes, cool! If not, this needs to be fixed (as hotfix?). In parallel, commonalities can be improved as smart here give inputs.

There are two other considerations for merging CAMARA documentation with OAI spec:

1. During my active coding days, in companies where we had inline documentation standard, we kept up well with documenting the interface endpoint and parameters, but the overall documentation at the top of the interface including 'user guide's still had serious bugs from time to time, with inconsistencies.
2. with inline documentation, Carriers may need to upskill tech-writers to write/wordsmith inline documentation. The premise is the OAI developer is not the best at producing final documentation, which is definitely true in my case.
   cc: @shilpa-padgaonkar @gmuratk @hdamker

[eric-murray]

The Swagger editor also supports linking to external documentation, for example:
https://editor.swagger.io/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/release-0.9.0/code/API_definitions/qod-api.yaml

I agree such links should be added to the release notes for each release.

With regard to the documentation itself, we need to distinguish between the mechanism by which APIs are documented, and the quality of that documentation. The introductory blurb (under info: description:) will always be the hardest to keep up to date, whether it is embedded in the API specification or a standalone markdown document.

But the value of using the API specification as the documentation is that OAS allows individual schema to have descriptions and examples, and good examples and descriptions can be included when the schema is introduced. So this stops documentation being viewed as something to be done right at the end when a new version of the API is otherwise ready.

So I think using these OAS features is the way to go towards keeping documentation up to date. Other tools, such as cucumber, will help to formalise the documentation of expected API behaviour. And whilst I agree that there is an obligation on API developers to try to keep inline documentation up to date and accessible to less technical viewers, I think there is also an obligation on those interested in such details to understand the way in which the associated tooling presents that information.

[eric-murray]

Agreed at meeting on 11th August to include links to release notes and README. Also raise in Commonalities.

[eric-murray]

@hdamker
The meeting consensus was to add links to the ReDoc and Swagger Editor formatted versions of a release to both the version release notes, and to the README (for the latest release). So something like:

• Formatted documentation (Swagger Editor) (ReDoc)

Can you make the necessary changes? Thanks.

[jpengar]

If it helps, in HomeDevicesQoD we have this PR camaraproject/HomeDevicesQoD#54 (ready to be merged) that you might want to use as a reference or example. @hdamker @eric-murray @jlurien.

[hdamker]

Can you make the necessary changes? Thanks.

Yes, will prepare a PR for that. Thanks for driving the issue to a conclusion.

[hdamker]

If it helps, in HomeDevicesQoD we have this PR camaraproject/HomeDevicesQoD#54 (ready to be merged) that you might want to use as a reference or example.

@jpengar thanks a lot, copied with pride 👍

[jpengar]

@hdamker Happy to hear that my PR was useful :)
Remember that the PR updates the README and CHANGELOG files, but you also need to update the release notes accordingly.
https://github.com/camaraproject/QualityOnDemand/releases

[hdamker]

@hdamker Happy to hear that my PR was useful :) Remember that the PR updates the README and CHANGELOG files, but you also need to update the release notes accordingly. https://github.com/camaraproject/QualityOnDemand/releases

Yes, I'm aware (hence I had written it in the PR description). I'm just waiting for one review from one of my fellow code owners (@RandyLevensalor @eric-murray) and then I will do the merge and update of release notes accordingly.

[murthygorty]

thank you so much everyone. I feel like we can use QoD as the leading example of CAMARA APIs :-) - it is also very popular for usage as far as I can tell.