search

camunda / camunda-docs

Camunda 8 Documentation, including all components and features
https://docs.camunda.io/
Other
51 stars 171 forks source link

Merge intro pages of new API explorers with existing ones and clean them up #3585

Open christian-konrad opened 3 months ago

christian-konrad commented 3 months ago

C.f. https://github.com/camunda/camunda-docs/pull/3569#issuecomment-2036337419

image

image

Each REST API now has two intro pages: The hand-written overview page, and the intro page auto-generated from OpenAPI specs.

We should consider merging them, or probably just not generate the auto-generated one. It adds one extra page for the user to navigate without any new info (the auth methods are also documented on dedicated auth pages).

christian-konrad commented 3 months ago

@pepopowitz this could be a potential topic for you

pepopowitz commented 3 months ago

Yes, this bothers me also.

The significant value on the generated introduction page is the description of the authentication methods. I almost think it would be better off named "Authentication" instead of "Introduction"....although then we'd have two "Authentication" pages.

I'm not really sure what to do about this, in a way that doesn't introduce tricky steps to the generation process. I'm open to ideas and suggestions....and I'll continue to think about it too.

christian-konrad commented 3 months ago

@pepopowitz isn't there a way to hook into the generator to skip that page, or hook into a step afterwards to delete it again?

pepopowitz commented 3 months ago

@pepopowitz isn't there a way to hook into the generator to skip that page, or hook into a step afterwards to delete it again?

I don't think I want to skip or delete that page. It does contain valuable information, re: the authentication schemes that are available, and license.

What do you think about renaming the page from Introduction to something else?