search

Mbed-TLS / mbedtls-docs

Version-independent documentation for Mbed TLS
Apache License 2.0
21 stars 28 forks source link

Remove unnecessary "Mbed TLS" from Getting Started heading #99

Closed davidhorstmann-arm closed 1 year ago

davidhorstmann-arm commented 1 year ago

We know which project's documentation we are in because of the site title. Repeating the project name is redundant and a little jarring.

Shorten the titles to be more intuitive.

tom-cosgrove-arm commented 1 year ago

Actually, I like the titles as they are

Being in "Mbed TLS docs", knowing "Long-term plans" are "Long-term plans for Mbed TLS" means I don't have to be thinking "is this long-term plans for cryptographic algorithm support?" or some such else

davidhorstmann-arm commented 1 year ago

Perhaps I can persuade you both with some screenshots from the website.

In this one we have "Getting started with Mbed TLS" under the main "Mbed TLS" project title. This is particularly odd since "API Reference" and "Project" are assumed implicitly to be relating to Mbed TLS: getting_started_mbedtls

The "Long-term plans" one is less jarring, admittedly, but it already falls under Mbed TLS > Project, so the context of "The Mbed TLS Project" is implied. I'd be happy to compromise and leave this one as-is, seeing as you could argue it's not fully clear what aspect of the project has long-term plans: project_mbedtls

What do you think?

tom-cosgrove-arm commented 1 year ago

Given those screenshots, "Project" is the thing that stands out as weird to me!

I might be inclined to suggest "Mbed TLS API Reference", but it seems entirely reasonable for "Long-term plans for Mbed TLS" and "External Reviewers" as they are. Possibly "Mbed TLS Roadmap" :)