Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SDK Reference suggestions #1800

Open
shepazon opened this issue Oct 23, 2024 · 0 comments
Open

SDK Reference suggestions #1800

shepazon opened this issue Oct 23, 2024 · 0 comments
Labels
documentation This is a problem with documentation. needs-triage This issue or PR still needs to be triaged.

Comments

@shepazon
Copy link
Contributor

Describe the issue

I have a few recommendations and suggestions for improvements to the AWS SDK for Swift Reference. Some of these are just for cleanup, while others are SEO related. I would be surprised if all of these happen, but each that does is likely to be a noticeable help for users and/or discoverability.

SEO changes

  • The title of the reference front page as displayed when it comes up on Google is just "Documentation" and there's no summary available:
    image
    This needs to be changed so the title is "AWS SDK for Swift Reference" and the summary is something useful, such as "Lists the Swift classes that implement each AWS service and API, with descriptions and details for each class and function."
  • The title of the top page for each service in the reference should ideally be something like " - AWS SDK for Swift Reference".
  • The title of each class's top page page should be ideally be something like ". - AWS SDK for Swift Reference".
  • Each function/type/etc subpage for a class should ideally be something like ".<function/type name> - AWS SDK for Swift Reference".

Usability changes

  • The first service category listed should be the SDK, not the support services.
  • The site home page would be more usable if if it listed of the categories of service with links to subpages containing the services in that category (AWS SDK for Swift, Smithy, AWS Runtime, whatever).
  • The lists of service names would be enhanced if they had a toggle that could be expanded to see a summary of what the service does. Just a sentence or two. Even just the full name of the service would be helpful.
  • The sidebar needs a link back to the SDK's marketing page (https://aws.amazon.com/sdk-for-swift/).
  • The sidebar needs a link back to the SDK Developer Guide (https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/home.html).
  • The "Overview" on the home page needs to be more than just saying the SDK is available on GitHub. It should include a brief description of what the SDK is.
  • There needs to be a copyright notice with license SPDX info. Ideally with a link to a copy of the full license available.
  • There should be an on-site search available. The only thing that looks like a search is a simple filter that only supports the three pages that are currently in the sidebar.
  • That filter needs to go away unless the sidebar gets very, very much longer.
  • Every page that isn't published to /latest/ should have a link (at the top somewhere, ideally, though not very large) to the latest version of the page. This might require JavaScript to show the link only if there is a newer version available. If totally necessary, the link could always be present, though it would possibly be confusing.

Links

https://sdk.amazonaws.com/swift/api/awssdkforswift/latest/documentation/awssdkforswift

@shepazon shepazon added documentation This is a problem with documentation. needs-triage This issue or PR still needs to be triaged. labels Oct 23, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation This is a problem with documentation. needs-triage This issue or PR still needs to be triaged.
Projects
None yet
Development

No branches or pull requests

1 participant