Repository navigation
Define standard for H1 titles in SDK readmes #105
Description
Activity
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?
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.
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-kitorably-kotlin-lobby-kitetc.Reacted by Quintin Willison and Stephane MoreauI like 'Kit', and have seen that elsewhere from others. Great suggestion, @tomkirbygreen.
Reacted by Stephane MoreauI had a call on this with @stmoreau and our Content Marketing Team this morning. We've decided to match GitHub repository descriptions with the
H1in theREADMEmarkdown files, in a reduced form.Inputs and thoughts contributing to us coming to this decision:
- GitHub populates the repository home page
title(inside HTMLhead, 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 atitlevalue 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
H1value 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-jsJavaScript, TypeScript, Node and React Native SDK ably/ably-javaJava, Kotlin, Android, Clojure and Scala SDK ably/ably-rubyRuby SDK ably/ably-asset-tracking-androidAndroid Asset Tracking SDK Because making these changes will require a change to
README.mdfiles 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.- GitHub populates the repository home page
Here's what we have at the time of creation of this issue:
My thoughts:
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.