Add design tenets to docs #466
Conversation
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
1 similar comment
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
docs/design/tenets.md
Outdated
|
|
||
| These are the tenets that drive the development of the AWS Kotlin SDK in priority order. | ||
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - The AWS ecosystem is split into 1000s of teams - but that doesn’t mean that customers should have to care. In the case of the Kotlin SDK customers shouldn’t need to decide between a “mobile” version and a “server” version of the SDK: there should be a single low-level AWS Kotlin SDK, that is consistent in style and capabilities to any other supported AWS SDK. |
There was a problem hiding this comment.
Comment: This tenet feels weakly worded to me. I think the point the first sentence is making is "it doesn't matter how many teams support AWS services, users only need one SDK". The differentiation between mobile and server feels like it belongs in 2 or 4. Is there a better example or principle of simplicity we could offer instead?
docs/design/tenets.md
Outdated
| @@ -0,0 +1,8 @@ | |||
| # AWS SDK for Kotlin Design Tenets | |||
|
|
|||
| These are the tenets that drive the development of the AWS Kotlin SDK in priority order. | |||
There was a problem hiding this comment.
Nit: AWS Kotlin SDK → AWS SDK for Kotlin
docs/design/tenets.md
Outdated
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - The AWS ecosystem is split into 1000s of teams - but that doesn’t mean that customers should have to care. In the case of the Kotlin SDK customers shouldn’t need to decide between a “mobile” version and a “server” version of the SDK: there should be a single low-level AWS Kotlin SDK, that is consistent in style and capabilities to any other supported AWS SDK. | ||
| 2. **Mobile is a full citizen** - The world is mobile and customers expect mobile use-cases to be represented with equal weight to their server-based counterparts. | ||
| 3. **Kotlin idiomatic** - A Kotlin SDK should be geared towards developers working in Kotlin. While it’s true Kotlin has very good Java inter-op, as well as bindings to JS, Native and objc/SWIFT - the primary target customer will be pure-Kotlin applications. This means that Kotlin-only concepts like coroutines and rich DSLs can and should be part of the primary API; with wrappers for other runtimes as appropriate. |
docs/design/tenets.md
Outdated
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - The AWS ecosystem is split into 1000s of teams - but that doesn’t mean that customers should have to care. In the case of the Kotlin SDK customers shouldn’t need to decide between a “mobile” version and a “server” version of the SDK: there should be a single low-level AWS Kotlin SDK, that is consistent in style and capabilities to any other supported AWS SDK. | ||
| 2. **Mobile is a full citizen** - The world is mobile and customers expect mobile use-cases to be represented with equal weight to their server-based counterparts. | ||
| 3. **Kotlin idiomatic** - A Kotlin SDK should be geared towards developers working in Kotlin. While it’s true Kotlin has very good Java inter-op, as well as bindings to JS, Native and objc/SWIFT - the primary target customer will be pure-Kotlin applications. This means that Kotlin-only concepts like coroutines and rich DSLs can and should be part of the primary API; with wrappers for other runtimes as appropriate. |
There was a problem hiding this comment.
Nit: Incorrect usage of semicolon
docs/design/tenets.md
Outdated
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - The AWS ecosystem is split into 1000s of teams - but that doesn’t mean that customers should have to care. In the case of the Kotlin SDK customers shouldn’t need to decide between a “mobile” version and a “server” version of the SDK: there should be a single low-level AWS Kotlin SDK, that is consistent in style and capabilities to any other supported AWS SDK. | ||
| 2. **Mobile is a full citizen** - The world is mobile and customers expect mobile use-cases to be represented with equal weight to their server-based counterparts. | ||
| 3. **Kotlin idiomatic** - A Kotlin SDK should be geared towards developers working in Kotlin. While it’s true Kotlin has very good Java inter-op, as well as bindings to JS, Native and objc/SWIFT - the primary target customer will be pure-Kotlin applications. This means that Kotlin-only concepts like coroutines and rich DSLs can and should be part of the primary API; with wrappers for other runtimes as appropriate. |
There was a problem hiding this comment.
Comment: Listing other languages in a Kotlin tenet feels contradictory. I'd favor simply saying "While Kotlin has bindings and interoperability with other languages, the primary use case will be Kotlin applications".
docs/design/tenets.md
Outdated
| 1. **Customer simplicity (aka Don’t Make Me Think)** - The AWS ecosystem is split into 1000s of teams - but that doesn’t mean that customers should have to care. In the case of the Kotlin SDK customers shouldn’t need to decide between a “mobile” version and a “server” version of the SDK: there should be a single low-level AWS Kotlin SDK, that is consistent in style and capabilities to any other supported AWS SDK. | ||
| 2. **Mobile is a full citizen** - The world is mobile and customers expect mobile use-cases to be represented with equal weight to their server-based counterparts. | ||
| 3. **Kotlin idiomatic** - A Kotlin SDK should be geared towards developers working in Kotlin. While it’s true Kotlin has very good Java inter-op, as well as bindings to JS, Native and objc/SWIFT - the primary target customer will be pure-Kotlin applications. This means that Kotlin-only concepts like coroutines and rich DSLs can and should be part of the primary API; with wrappers for other runtimes as appropriate. | ||
| 4. **Multi-platform** - One of the key benefits of Kotlin is that it enables the ability to “write-once, run in many places”. The AWS SDK for Kotlin should support customers use-cases across the set of stable Kotlin target platforms. |
There was a problem hiding this comment.
Nit: use-cases → use cases
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
docs/design/tenets.md
Outdated
|
|
||
| These are the tenets that drive the development of the AWS SDK for Kotlin in order of priority. | ||
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - Kotlin SDK customers shouldn’t need to decide between different variants of the SDK. Rather, there is a single AWS Kotlin SDK providing support for all customer use cases with functionality on par with other AWS SDKs. The SDK itself should provide access to AWS services with obvious, flexible, and convienent APIs. |
There was a problem hiding this comment.
I don't understand what you mean by 'variants of the SDK'
One of the tenets we had on the Java team was 'Make simple things simple and complex things possible' the idea was that you optimized for the simple "base case" but also left the door open to power users to be able to tweak things if they were willing to get their hands dirty.
There was a problem hiding this comment.
I believe this particular stanza was written before the Kotlin SDK existed and was referring to all/any of the various SDKs developers could choose from when building mobile apps (java v1, v2, amplify). Agree that it doesn't make sense in a larger context and will re-word more along the lines of your call-out.
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
docs/design/tenets.md
Outdated
| These are the tenets that drive the development of the AWS SDK for Kotlin in order of priority. | ||
|
|
||
| 1. **Customer simplicity (aka Don’t Make Me Think)** - Kotlin SDK customers shouldn’t need to decide between different variants of the SDK. Rather, there is a single AWS Kotlin SDK providing support for all customer use cases with functionality on par with other AWS SDKs. The SDK itself should provide access to AWS services with obvious, flexible, and convienent APIs. | ||
| 2. **Mobile is a full citizen** - The world is mobile and customers expect mobile use-cases to be represented with equal weight to their server-based counterparts. |
There was a problem hiding this comment.
Nit: One more stray hyphen in "use-case".
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
There was a problem hiding this comment.
This is a better start, thanks for taking it on.
The things that come to mind off top of my head:
Mobile is a full citizenis sort of redundant with multiplatform. If we consider Android part of KMP (which it is) then this could probably be rolled into the other tenent.- Tenets are supposed to help drive decisions in the face of ambiguity or contention (e.g.
secure, reliable, performant in that order). I think 1, 3, an 4 fit that bill (although 1 may be highly subjective to apply in practice)
|
I agree that 2 is a case of 4, as called out by @aajtodd . Updating to remove 2 accordingly. |
|
Kudos, SonarCloud Quality Gate passed!
|
|
A new generated diff is ready to view: __generated-main...__generated-docs-design-tenets |
4 participants
Issue #
(none)
Description of changes
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.