Renamed doc filename and xrefs to include token

[michelle-purcell]

Renamed the doc source file security-oidc-bearer-authentication-concept.adoc → security-oidc-bearer-token-authentication-concept.adoc and all xrefs to it.

Added a URL redirect also in the quarkusio.github.io repo for when this change goes live on the doc portal site: 1708

[michelle-purcell]

@sberyozkin - Fixing this deferred SME request from the last phase.
(@sheilamjones - FYI)

[sberyozkin]

Hi @michelle-purcell, thanks very much, it look fine, just a quick question. Is it important to have -concept in the doc name ? For example, security-oidc-bearer-token-authentication.adoc seems quite precise, security-oidc-bearer-token-authentication-concept.adoc is OK, but do we have to express this doc is concept in the actual doc name ?
If it is the best practice then yeah, lets do it, if we can optimize then I can create another issue afterwards so that we can drop -concept in all the concept doc file names ?

[sberyozkin]

Thanks Michelle for taking care of it

[michelle-purcell]

@sberyozkin - Thanks Sergey for reviewing.

Today, the Quarkus doc contributor guidelines and templates request the content type at the end. I think the quarkusio doc landing page builder (index) uses either the filename or ID to determine the content type heading to place the guide under.

But... in saying that. I like this suggestion to remove the content type from the end of a file name. I think it creates extra churn and longer file names. Also, the diataxis framework recognizes that content types are not one-size fits all, and the guidelines do acknowledge cross-pollination in the 'real world'. Other organizations that do diataxis don't include the content type in the filename.

@ebullient - WDYT? Should we remove the filename guideline to always include content type or would that pose a big issue with the implementation?

[sberyozkin]

Yes, the actual doc content makes it clear what it is, Concept, How To etc. At the URL level, the shorter URL the easier it is to follow them, so if we can optimize a bit and remove Diataxis qualifiers from the file names it would be not bad IMHO.

May be it is better to open a dedicate issue to discuss.

Cheers

[github-actions]

🙈 The PR is closed and the preview is expired.

[ebullient]

It's fine. I was using the filename as a way to tell if the content had been revised or not.. (that is where the classification for the site, the type, originally comes from).

We could use a category instead.. (and verify that the category doesn't appear twice). In the case of similarly named files, the suffix can be useful to disambiguate, but I agree that's probably case by case.

[sberyozkin]

Thanks @michelle-purcell @ebullient, I can open an issue to review which file names for the already refactored docs might be optimized

[sberyozkin]

@michelle-purcell I'll keep this PR open till Monday - I'm just not sure right now how you'd prefer to handle a possible optimization. If you and Erin agree then another option might be to update this PR and #1708. So I'll wait till Monday...

Thanks

[michelle-purcell]

@sberyozkin, @RuanNunes, @ebullient - Thanks.
Sorry for slow reply. I was on PTO yesterday. 👍 +1 from me to merging this one as-is and then removing the diataxis content type from all doc files that need it as a separate issue and PR. Would be good to test this first also.

[sberyozkin]

Hey @michelle-purcell Np at all, sounds good, let me merge it now, and then I'll open another issue to consider a possible optimization, thanks