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

Use the official docs for external docs, not the marketing page #12

Merged
merged 1 commit into from Mar 15, 2019

Conversation

Projects
None yet
2 participants
@pimterry
Copy link
Contributor

pimterry commented Mar 14, 2019

Very tiny simple PR, that I thought might be useful to totally separate from the other massive one.

This changes the externalDocs links from URLs like https://aws.amazon.com/s3/ to URLs like https://docs.aws.amazon.com/s3/, which are much more useful and docs-like (imo).

Note that both now and with this change, these URLs aren't correct for all services. There doesn't seem to be a system, e.g.:

This works for most of them though, especially the popular cases. Might be nice to improve in future, ok for now imo.

@MikeRalphson

This comment has been minimized.

Copy link
Contributor

MikeRalphson commented Mar 15, 2019

I'm trying to recall if there was any reason it was done like this originally. My only thought was perhaps the 'marketing' docs pointed at the technical docs but not the other way around, so it was better to enter at the 'top of the tree' so to speak?

@pimterry

This comment has been minimized.

Copy link
Contributor Author

pimterry commented Mar 15, 2019

They don't very clearly point to the docs though, it's a bit of a hunt. There's no one clear link, and the route from each is different. From https://aws.amazon.com/rds, you can go Resources, then Amazon AWS Documentation, and then you get most of the same content. For https://aws.amazon.com/ec2/ it's Resources -> Developer Resources -> Documentation. It's all just a bit more awkward, and not very convenient.

Agree it's a bit subjective, but the specs do specifically say this should link to documentation, and that does seem to be the convention everywhere else. E.g. the Slack spec links to https://api.slack.com/web, not https://slack.com, and the Github spec links to https://developer.github.com/v3/.

@MikeRalphson MikeRalphson merged commit 3a2092a into APIs-guru:master Mar 15, 2019

@MikeRalphson

This comment has been minimized.

Copy link
Contributor

MikeRalphson commented Mar 15, 2019

Thanks for clarifying - part of the reason for asking was to get the thought process documented in the issue. Thanks again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.