Skip to content

Commit

Permalink
feat: add sdks and libraries section
Browse files Browse the repository at this point in the history
Resolves #18 by introducing the SDK and Libraries section to provide a clear framework for
integrating SDKs and libraries across various platforms. The changes include:

1. An **Introduction** article that outlines the purpose of this section and the importance of
   maintaining a coherent ecosystem of development tools. It includes a decision flowchart to
   visually guide the integration process of new SDKs or libraries.

2. **Platform-specific template** for documenting recommended SDKs and libraries. Each template
   features a prioritization matrix to categorize the tools based on their necessity and utility.
  • Loading branch information
jboix committed Apr 15, 2024
1 parent 03ffa15 commit 5b1e722
Show file tree
Hide file tree
Showing 4 changed files with 158 additions and 1 deletion.
4 changes: 4 additions & 0 deletions public/_sidebar.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,7 @@
* [Pull Request Manual](/guides/PULL_REQUEST_GUIDE.md)
* [Code of Conduct Guidelines](/guides/CODE_OF_CONDUCT_GUIDE.md)
* [Security policy Guidelines](/guides/SECURITY_GUIDE.md)

**SDK and Libraries**

* [Introduction](/sdks/INTRODUCTION.md)
8 changes: 7 additions & 1 deletion public/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,18 @@
relativePath: true,
loadSidebar: true,
themeColor: '#00af91',
subMaxLevel: 2
subMaxLevel: 2,
}
</script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script src="//unpkg.com/docsify-plugin-flexible-alerts"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>
<script type="module">
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
mermaid.initialize({ startOnLoad: true });
window.mermaid = mermaid;
</script>
<script src="//unpkg.com/[email protected]/dist/docsify-mermaid.js"></script>
</body>
</html>
74 changes: 74 additions & 0 deletions public/sdks/INTRODUCTION.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# SDK and Libraries

This section provides comprehensive guidelines and a structured decision-making process for
selecting, updating, and integrating SDKs and libraries. It aims to standardize tool usage across
the company, ensuring efficiency and reducing technical debt.

## Benefits of a Coherent Ecosystem

1. **Improved Collaboration:** Using a consistent set of tools enhances team synergy and project
predictability.
2. **Streamlined Onboarding:** A standardized toolkit simplifies the onboarding process, enabling
quicker team member ramp-up.
3. **Better Productivity:** Common tools decrease redundancy, helping developers focus on innovation
rather than compatibility issues.
4. **Risk Management:** Well-supported tools reduce security vulnerabilities.
5. **Cost Efficiency:** Proper tool management cuts unnecessary costs associated with frequent
technology shifts.

## SDK/Library Integration Decision Chart

The flowchart below serves as a tool to guide the decision on whether to integrate a new SDK or
library. Use it to ensure that any addition is beneficial and sustainable.

```mermaid
%%{init: {"flowchart": {"defaultRenderer": "elk"}, "theme": "dark"} }%%
flowchart TD
A[Consider a new SDK/Library] --> B[Is it already in use<br>within the company?]
B --> |No| F[Is it well supported and<br>regularly updated?]
B --> |Yes| I[Does it align with our<br>technology stack and standards?]
I --> |Yes| C[Is the existing version<br>adequate?]
I --> |No| L
F --> |No| L
F --> |Yes| H[Does it align with our<br>technology stack and standards?]
H --> |No| L
H --> |Yes| J[Is there a better or similar<br>tool already in use?]
J --> |No| M[Does it significantly<br>improve development<br>efficiency or capability?]
J --> |Yes| L
M --> |No| L
M --> |Yes| W
C --> |No| D[Can it be updated<br>to a satisfactory version?]
C --> |Yes| W
D --> |No| L
D --> |Yes| W
W[fa:fa-check Integrate the SDK]
L[fa:fa-close Reject the SDK]
style A fill:#1565C0
style W fill:#2E7D32
style L fill:#C62828
```

## Platform-Specific Guidelines

Refer to the pages dedicated to each platform for detailed information on recommended and essential
tools:

- **[Android SDKs and Libraries](./_PLATFORM_TEMPLATE.md)**
- **[Apple SDKs and Libraries](./_PLATFORM_TEMPLATE.md)**
- **[Backend SDKs and Libraries](./_PLATFORM_TEMPLATE.md)**
- **[Data Handling Kits and Libraries](./_PLATFORM_TEMPLATE.md)**
- **[Infrastructure SDKs](./_PLATFORM_TEMPLATE.md)**
- **[Web SDKs and Libraries](./_PLATFORM_TEMPLATE.md)**

Each section provides curated lists of tools, integrating the decision-making principles from the
chart to ensure optimal tool selection and usage. This approach not only enhances efficiency but
also aligns with strategic development goals.
73 changes: 73 additions & 0 deletions public/sdks/_PLATFORM_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# [Platform] Development Kits and Libraries

This page outlines the recommended Development Kits and Libraries for [Platform] development. It
categorizes tools into **Must-Have**, **Should-Have**, based on necessity, and assesses their
utility to aid in selection. This guide ensures that all tools align with our company’s standards
and best practices.

## Overview

Below is a prioritization matrix that categorizes SDKs and libraries based on their utility and
necessity. This visual guide helps in quick decision-making regarding tool adoption.

```mermaid
%%{init: {"theme": "dark"} }%%
quadrantChart
title SDKs and Libraries Prioritization Matrix for [Platform]
x-axis Low Utility --> High Utility
y-axis Should Have --> Must Have
quadrant-1 Adopt
quadrant-2 Mandatory
quadrant-3 Optional
quadrant-4 Optional
SDK1: [0.9, 0.9]
SDK2: [0.2, 0.9]
Library1: [0.8, 0.3]
Library2: [0.1, 0.2]
```

For guidance on integrating or rejecting libraries and SDKs not listed in this guide, please consult
the [SDK/Library Integration Decision Chart](./INTRODUCTION?id=sdklibrary-integration-decision-chart).
Update this guide with your findings on new libraries and SDKs to ensure it remains a valuable
resource for your colleagues.

To view deprecated tools and their alternatives, visit
the [Deprecated Libraries and SDKs Section](#deprecated-kits-and-libraries).


> [!Note]
> The recommendations on this page are based on general guidelines which may not perfectly fit all
> project scenarios. Evaluate the specifics of your project when choosing tools.
## Must-Have Kits and Libraries

These are the essential tools required for development on [Platform]. They are supported actively
and are pivotal to our development practices.

- **SDK/Library Name 1**
- **Purpose**: Explains its functions and why it is indispensable.
- **Official Documentation**: [Link to documentation](#)
- **References**: [Link to projects using this SDK/library](#)

_Continue listing other must-have SDKs and libraries as necessary._

## Should-Have Kits and Libraries

These tools, while not mandatory, are recommended as they enhance productivity and address common
issues effectively.

- **SDK/Library Name 1**
- **Purpose**: Describes what it does and its benefits.
- **Official Documentation**: [Link to documentation](#)
- **References**: [Link to projects using this SDK/library](#)

_Continue listing other should-have SDKs and libraries as necessary._

## Deprecated Kits and Libraries

These tools are no longer recommended due to reasons such as obsolescence, lack of support, or the
availability of better alternatives.

- **SDK/Library Name 1**
- **Reason for Deprecation**: Explains why the tool is deprecated.
- **Suggested Alternatives**: [Link to alternative tool's documentation](#)

0 comments on commit 5b1e722

Please sign in to comment.