Define standard for H1 titles in SDK readmes

[QuintinWillison]

Here's what we have at the time of creation of this issue:

Repository	Contents of current H1
ably-common	Ably - Common Resources
ably-js	Ably
ably-java	Ably
ably-cocoa	Ably iOS, tvOS and macOS Objective-C and Swift client library SDK
ably-dotnet	ably-dotnet
ably-go	Ably Go
ably-ruby	Ably
ably-python	Ably
ably-php	Ably
ably-flutter	Ably Flutter Plugin
ably-asset-tracking-common	Ably Asset Tracking SDKs - Common Resources
ably-asset-tracking-android	Ably Asset Tracking SDKs for Android
ably-asset-tracking-swift	Ably Asset Tracking SDKs for Swift & Objective-C
ably-asset-tracking-js	Ably Asset Tracking SDK for JavaScript

My thoughts:

• Given [we now have a standard opening "about" section|https://github.com/ably/ably-common/pull/102], which contains a hyperlink to our [main website|https://ably.com], then I don't think it's necessary to continue to have hyperlinks in the main H1. Furthermore that has always seemed a little inappropriate to me for heading contents.
• We should minimise (perhaps eliminate) the amount of "embedded markdown" in headings as it adds cognitive load to readers - in particular for those who elect to read the document in raw form.
• We should not simply repeat the machine-readable name from the repository URL (e.g. {{ably-dotnet}}) - the readme is intended to be human-readable, so headings should conform as such.
• Always use "SDK" in headings, dropping "client library" (it can appear in body contents)
• Never use "SDKs", replace with "SDK" - even though, technically, AAT does contain multiple SDK packages
• We need to decide if we're going to focus on languages, frameworks or both in the top level headings - e.g. even for AAT we have "Android" vs "Swift & Objective-C"

Once the decision has been made then it will be captured in the [sdk-readme template|https://github.com/ably/ably-common/blob/main/templates/sdk-readme.md] as the actionable work to be undertaken under this issue.

[marklewin]

FWIW I agree with just about everything here, with the exception of "no SDKs". SDK = Software Development Kit, so the plural is Software Development Kits, therefore I think that's perfectly acceptable for situations like AAT.

Regarding "languages, frameworks, or both?" let's always aim for clarity and discoverability by including both platform and language in the heading. E.g "Ably Asset Tracking for iOS: Swift SDK". In this example we can also link to the Obj-C SDK as an alternative in the intro?

[AndyNicks]

We need to decide if we're going to focus on languages, frameworks or both in the top level headings - e.g. even for AAT we have "Android" vs "Swift & Objective-C"

I would also like to stick to the SDK naming convention and focus on either the language or platform / framework, but I'm afraid we might not be able to do that in real life. For example: some of our SDKs are for platforms (Android, Cocoa), some are for languages (PHP, Python) and some are for platforms (Laravel, Flutter). I believe that we should call the SDK convenient for our customers, and not follow any strict scheme.

[tomkirbygreen]

I like the standardisation around 'SDK' rather than 'client library'. We might want to give some thought to how we're going to name higher-level SDKs that address a specific customer vertical, such as a Lobby SDK for multiplayer gaming. Such higher-level SDKs are within the remit of the Reach Pod and will by necessity be coupled to a language. I was wondering about 'Kit' as a discriminating collective, as in ably-js-lobby-kit or ably-kotlin-lobby-kit etc.

[QuintinWillison]

I like 'Kit', and have seen that elsewhere from others. Great suggestion, @tomkirbygreen.

[QuintinWillison]

I had a call on this with @stmoreau and our Content Marketing Team this morning. We've decided to match GitHub repository descriptions with the H1 in the README markdown files, in a reduced form.

Inputs and thoughts contributing to us coming to this decision:

• GitHub populates the repository home page title (inside HTML head, used by browsers to label the tab, used by Google in search results) in the form "org-name/repository-name: repository-description" - so, for example, right now our JS SDK has a title value of "ably/ably-js: Javascript, Node, Typescript, React Native client library SDK for Ably realtime messaging service"
• Google does not appear to be using the H1 value in search results
• Visitors already know it's Ably, often that's their search intent, so we don't need to repeat the brand name in the title
• Additional words like "client library" don't add value as "SDK" is enough
• Google picks up the description in search results from the content in our readme, seemingly the content just below the H1
• SEO best practice guides us to keeping:
  • title lengths 60 characters or less
  • description lengths 160 characters or less (something we clearly have much less control of)

I'll not illustrate for every SDK but here are some example repository description values going forwards, which are to be also copied to H1 values:

Repository	Description Value
ably/ably-js	JavaScript, TypeScript, Node and React Native SDK
ably/ably-java	Java, Kotlin, Android, Clojure and Scala SDK
ably/ably-ruby	Ruby SDK
ably/ably-asset-tracking-android	Android Asset Tracking SDK

Because making these changes will require a change to README.md files across our SDK repositories, we will also tweak the opening boilerplate Ably content at the same time. We will remove detail that can change over time (e.g. customer names) to reduce maintenance overhead.