During my last Microsoft Teams App Dev Accelerator cohort, I spent more time than I’d like helping developers find accurate documentation for Teams SDKs. Not minutes… hours, sometimes for a single feature.
Not because the information doesn’t exist. It usually does. But finding it requires knowing where to look across multiple Microsoft properties, understanding which SDK versions are current versus deprecated, and recognizing which code samples have been validated against current APIs.
To be clear, I’m not criticizing Microsoft’s technical writers. The individual docs are often quite good. The challenge is structural: Microsoft Teams documentation is spread across multiple domains with inconsistent versioning and limited discoverability for what’s actually current.
Here’s the thing: the documentation problems fall into two categories that compound each other.
Outdated Recommendations in Official Docs
Official documentation often recommends tools and approaches that, while not wrong, don’t frequently reflect the current guidance.
Take ngrok as an example. Microsoft Learn’s Teams documentation still recommends ngrok when testing bots or message extensions (examples here & here) to expose your local web server to a publicly routable endpoint so the Teams bot infrastructure can communicate with your localhost. Ngrok is a solid tool and it works. But Microsoft has since released dev tunnels, their own service that serves the same purpose. The Teams tooling now has dev tunnels baked in, spinning it up automatically during F5 debugging. Ngrok shouldn’t be the primary recommendation anymore.
It’s not that ngrok is broken or that developers who use it are doing something wrong. It’s that someone following the official docs doesn’t know there’s a better, more integrated option available. They’re learning patterns that experienced developers have moved past.
Overlapping SDKs with Unclear Boundaries
The second challenge is more frustrating: multiple SDKs created by different teams at Microsoft that appear to serve the same purpose, or have significant overlap in functionality.
Building a chatbot? Should you use the Teams SDK or the Microsoft 365 Agents SDK?
When you’re building a Teams app and you discover two or three SDKs that seem to do similar things, the natural question is: “Which one should I use?” The documentation rarely answers this clearly. You end up reading through multiple SDK docs, trying to piece together which one is current, which one is deprecated, and which one is intended for your specific scenario.
This isn’t a documentation quality problem. It’s an organizational reality. Different product teams ship different SDKs on different timelines, and it sure seems from the outside there’s limited coordination around how developers are supposed to understand the landscape.
Let me show you what that landscape looks like, and more importantly, how to navigate it successfully.
Documentation Scattered Across Five Domains
Microsoft Learn: The Challenge of Finding Current Guidance
Microsoft Learn is Microsoft’s unified documentation platform. For Teams development, it contains documentation for every approach Microsoft has recommended over the years, but with inconsistent indicators of what’s still current versus what’s been superseded.
Here’s a real example of the confusion developers face. Search Microsoft Learn for “Teams bot authentication” and you’ll find results for:
- Bot Framework SDK authentication (no longer the recommended approach as of 2023)
- TeamsFx authentication helpers (deprecated September 2025, scheduled for retirement mid-2026)
- Teams AI Library authentication (the v1 library was deprecated March 2024)
- Teams SDK authentication (current, formerly called Teams AI Library v2)
All four appear as valid options. Only one is recommended for new development. The challenge is that deprecated content doesn’t always have clear warnings, and you need to understand the SDK timeline to recognize what’s current.
The SDK Naming Problem
The naming situation deserves its own callout because it’s genuinely confusing, and it’s not the developer’s fault for being confused.
The Teams AI Library v2 was finally renamed to the Teams SDK in November 2025, a solid 2 months after it went GA. That name makes sense on its own, but it creates a new problem: for years, developers informally called TeamsFx “the Teams SDK.” Now there’s an actual Teams SDK that’s a completely different thing.
Then there’s the Teams JavaScript Client Library, which is used for client-side scenarios. The documentation doesn’t explicitly say it’s retiring, but the page includes the same retirement callout that appears on the TeamsFx documentation. So is the Teams JavaScript Client Library being treated as part of TeamsFx? It’s a completely separate package with a different installation process. The documentation doesn’t clarify the relationship.
To add another layer: the Teams SDK itself contains both server-side and client-side functionality, and the documentation doesn’t always make it clear which components are intended for which scenarios.
If you’re a developer trying to start a new Teams project and you want to know “which SDK should I use?”, the documentation doesn’t give you a clear answer. You’re left piecing together information from multiple pages, blog posts, and GitHub repos to understand the current landscape.
The Update Cycle Gap
Microsoft Learn also has longer update cycles than the SDKs themselves. When Microsoft announces changes at conferences or ships new SDK versions, it can take weeks for the official documentation to reflect those changes. During that gap, developers following the official docs may be learning approaches that are already outdated.
This isn’t a criticism of the documentation team. It’s a structural challenge: documentation review processes are thorough, which takes time, but SDK releases happen on a faster cadence.
I don’t think an SDK should be considered ready for release without, at a minimum, complete documentation & working code samples.
GitHub Pages: Where Current SDK Documentation Lives
Historically, the most up-to-date Teams SDK documentation lived outside Microsoft Learn entirely; it lived in GitHub repositories, published as GitHub Pages sites.
The Teams SDK documentation was originally only available in via GitHub Pages from the source repo, but it’s since been ported to the official Microsoft Learn site. The Microsoft 365 Agents SDK documentation is hosted similarly, initially only in a GitHub repo only to later make its way to Microsoft Learn. Actually, it was worse… there were NO docs for the JavaScript implementation of the SDK when it was released - those weren’t available until months after the release.
The tradeoff is discoverability. These GitHub Pages sites don’t rank as highly in search results as Microsoft Learn content. Microsoft Learn doesn’t always link to them prominently. Unless you know these sites exist and bookmark them directly, you might not find them when searching for answers.
Granted, the docs for both of these SDKs are now in Microsoft Learn, but they should never have been released with the GA milestone until the docs & associated samples were available at the same time.
When I teach workshops, I spend time at the beginning making sure everyone has the right documentation URLs bookmarked. It’s not that the information is hidden; it’s that the discovery path isn’t intuitive.
DevBlogs: Important Announcements with Limited Discoverability
The Microsoft 365 Developer Blog is where Microsoft publishes important announcements about Teams platform changes: breaking API changes, deprecation notices, new feature launches. These announcements often appear on DevBlogs before they’re reflected in the official documentation.
The challenge is finding these announcements later. DevBlogs is designed for timely news, not as a reference resource. The search functionality is basic, and blog post URLs don’t tend to rank well in search engines for technical queries.
Critical information like the Teams AI Library v1 deprecation was announced on DevBlogs in May 2025 when the Teams AI Library v2 beta was released. If you weren’t following the blog that week, finding that announcement months later when you realize your code uses deprecated APIs takes some digging. And now, that post is gone…
This isn’t unique to Microsoft. Most corporate blogs prioritize fresh content over archival search. But for Teams developers, it means that important platform decisions are announced in a format that’s hard to reference later.
Tech Community: Valuable but Requires Context
Microsoft’s Tech Community forums contain a mix of Microsoft employee responses, MVP guidance, and community answers. It’s a valuable resource for specific issues, especially edge cases that aren’t covered in official docs.
The challenge is context. Answers from 2020 appear alongside answers from 2025 with no clear indication of which SDK version they reference. An accepted solution might use APIs that have since been deprecated. Microsoft employee responses in one thread might reflect guidance that changed by the time another thread was answered.
I’ve seen threads where Microsoft employees provide different answers to similar questions just a few months apart. That’s not a quality problem; the platform genuinely changed between those threads. But nobody went back to update the older answers, so both appear equally valid to someone searching today.
Like any resource, when using Tech Community, always check the source of the answer as well as the date of the question/response and mentally map it to what SDK versions were current at that time.
Azure Documentation: A Separate Documentation Tree
Azure documentation for Teams-related services (Azure AI Bot Service, Azure Communication Services, Azure AI) exists in its own documentation structure with its own organization, search, and version management.
When building Teams apps that use Azure services, which many production Teams apps do, you need to cross-reference between Microsoft Learn’s Teams docs and Azure docs. The two documentation sets sometimes use different terminology for related concepts, different API patterns, and make different assumptions about what developers already know.
Authentication is a good example of where this gets tricky. There are authentication scenarios that are completely valid for Teams apps but aren’t well covered in Microsoft Entra ID’s documentation. Nested App Authentication (NAA) is a perfect example: it’s a legitimate pattern for Teams apps and Office Add-ins, but it feels unique to those platforms.
Is NAA a native pattern in Entra ID that just happens to be used by Teams and Office, or is it something specific to those platforms? The documentation doesn’t make that clear, so developers are left guessing about where to look for guidance and how broadly these patterns apply.
Quality Issues That Cost Developer Hours
Documentation fragmentation would be easier to navigate if the content itself was consistently accurate. In practice, quality varies.
Code Samples That Don’t Work as Written
I’ve encountered code samples in Microsoft Learn that don’t work as published. Import statements for packages that have been renamed or removed. API calls with parameter types that don’t match the current SDK version. Configuration examples that reference services or endpoints that are no longer available. The build up of technical documentation and sample project debt is real… and there’s zero incentive for Microsoft to clean it up or even indicate that a sample is old. That leaves customers trying to figure out if it’s just old yet still relevant, or if it’s old and outdated?
Over the years, I’ve submitted documentation PRs to fix issues like these. Mistakes happen in any documentation set this large; that’s not surprising. The challenge is that quality control isn’t consistent across all content. Some documentation clearly goes through rigorous technical review. Other pages appear to have less validation before publication.
For developers learning a new SDK, this creates a frustrating experience: when sample code doesn’t work, you can’t easily tell whether you’re doing something wrong or whether the documentation itself has an error. That uncertainty adds time to every debugging session.
New SDKs Released Without Adequate Learning Resources
This is a pattern I’ve seen repeatedly with Teams development, and it extends to other parts of the Microsoft 365 developer experience as well: when a new SDK is released, there often aren’t enough documentation, samples, or examples to help developers understand how to use it effectively.
When the Teams SDK (formerly Teams AI Library v2) was released, there were very few code samples and minimal documentation showing how to actually use it. Even the unit tests in the source code, which can be a valuable resource for understanding intent, weren’t fleshed out enough to serve as learning material.
Think about it this way: it’s like shipping a new product without an instruction manual that explains how everything works and provides examples. Developers are left asking questions to engineers who are already working on the next thing and can’t respond quickly.
Here’s what I’d consider a reasonable baseline for an SDK release:
- Ideal: Tutorials, examples, and conceptual documentation published alongside the SDK
- Acceptable: If full documentation isn’t ready, at minimum provide code samples in the public GitHub repo that demonstrate common scenarios
- Bare minimum: Well-documented unit tests that show the intended usage patterns, with code comments explaining the “why”
When these resources aren’t available, developers resort to trial and error. And it’s not just a human problem: AI coding assistants struggle with under-documented SDKs too. Without clear examples of intent, they make things up, which leads developers down wrong paths that waste even more time.
I don’t think an SDK should be considered “released” if developers don’t have the resources to actually learn how to use it.
Breaking Changes Without Documentation Updates
Occasionally, SDK updates ship with breaking changes before the documentation is updated to reflect them. You upgrade an SDK, your code breaks, and the documentation still shows the old API signature.
In November 2024, the Microsoft 365 Agents SDK changed how environment variables were loaded. Apps that worked in version 0.5.0 failed in 0.6.0. The documentation wasn’t updated for about three weeks. During that gap, developers encountered failures with no explanation in the official docs.
Community members figured out the issue and posted workarounds on GitHub Issues. Eventually the documentation was updated. But for those three weeks, developers had to rely on community resources to understand what changed.
This is a side effect of the velocity tradeoff mentioned earlier: SDKs ship faster than documentation can keep up.
Version Information That’s Hard to Parse
Documentation versioning isn’t consistent across Microsoft Learn. Some pages have version selectors that let you choose which Teams API version to view. Other pages show examples from multiple SDK versions on the same page with limited indication of which example applies to which version.
The Teams JavaScript Client Library documentation shows v1 and v2 examples side by side. That’s helpful for comparison, but it can be confusing for developers who just want to know “what should I use for a new project?” The docs could more clearly indicate that v2 is recommended for new development.
Why the Documentation Landscape Looks This Way
Why is Teams documentation spread across so many places? The structure reflects how Microsoft is organized internally.
Different teams own different parts of the documentation:
- The Microsoft 365 developer platform team owns Microsoft Learn content
- Individual SDK teams own their GitHub Pages documentation
- Announcements are published to the Microsoft 365 Developer blog
- The Azure documentation team manages Azure-related content
- Community forums are managed by yet another team
Each team follows different publication processes, update schedules, and quality standards. There isn’t a central coordination layer ensuring consistency across all of these domains.
The Velocity vs. Discoverability Tradeoff
I asked Microsoft documentation team members why Teams SDK documentation (formerly Teams AI Library v2) lives on GitHub Pages instead of Microsoft Learn. The answer makes sense once you understand the constraints: velocity.
SDK teams need to update documentation with every release. Microsoft Learn’s publication process involves multiple review stages and can take weeks. GitHub Pages can be updated instantly with every code commit.
That’s the tradeoff: the most current, accurate documentation for actively developed SDKs lives outside Microsoft’s official documentation platform because that’s the only way to keep it in sync with the code. Discoverability suffers, but accuracy improves.
So in the meantime, why not update Microsoft Learn’s official Teams developer pages to just say something along the lines of “check this site for the latest docs, we’re in the process of bringing them into Microsoft Learn.”
At least a customer would have a clear picture of the current state!
The Gap Between Tutorials and API References
Microsoft’s documentation strategy generally targets two audiences: beginners who need step-by-step tutorials and experienced developers who need API references.
The challenge is that most Teams developers don’t fit neatly into either category. They’re experienced developers who are new to Teams. They already know how to code; what they need is conceptual explanations, architectural guidance, and decision frameworks to help them understand the Teams platform specifically.
That middle ground, the content that helps experienced developers get oriented in a new platform, is often the hardest to find. Microsoft Learn does tutorials and API references well. The in-between content is where the gaps tend to appear.
How I Navigate Teams Documentation
After years of working with Teams development, here’s the approach I’ve found works well:
Start with GitHub Pages for SDK-specific questions. Bookmark the GitHub Pages URLs for any SDK you’re using. These docs stay in sync with the code and are typically the most current source.
Use Microsoft Learn for conceptual overviews. The high-level architecture documentation on Microsoft Learn is usually accurate even when specific SDK guidance has drifted. It’s a good starting point for understanding how pieces fit together.
Check the Microsoft 365 Developer blog before upgrading SDKs. Before upgrading any SDK version, search for announcements about that SDK. This helps you catch breaking changes that might not be reflected in the documentation yet.
Test code samples before relying on them. Don’t assume sample code works as written. Run it first, even if it comes from official Microsoft documentation.
Search GitHub Issues when something doesn’t work as documented. If the documentation says one thing but you’re seeing different behavior, check the SDK’s GitHub Issues. Someone else has likely encountered the same problem and documented a workaround.
Validate Across Multiple Sources
For any significant architectural decision, I verify information across multiple sources before committing to an approach:
- Official documentation (Microsoft Learn or GitHub Pages)
- Community resources (GitHub Issues, Stack Overflow, Tech Community)
- First-hand testing (actually run the code and verify the behavior matches what you expect)
If multiple sources agree, the information is probably reliable. If they conflict, dig deeper before building on that foundation.
What I Cover in My Workshops
When developers take my workshops or hire me for coaching, documentation navigation ends up being part of the curriculum. Not because the students can’t read, but because knowing where to look and what to trust is genuinely a learned skill.
I cover things like:
- Which URLs to bookmark and trust for different SDKs
- How to identify deprecated content when warnings aren’t obvious
- Where to look for breaking changes before upgrading
- How to verify information before building on it
- Which community resources fill the gaps in official documentation
In a better world, this wouldn’t need to be part of a Teams development curriculum. But given the current landscape, understanding how to navigate the documentation is part of being effective as a Teams developer.
Looking for a Faster Path Through the Documentation Landscape?
My Microsoft Teams development courses include curated documentation resources and verified code samples that work with current SDK versions.
I’ve done the research to separate current guidance from deprecated approaches, so you can focus on building.
Check out my courses or book a coaching call to discuss your specific challenges.
Microsoft MVP, Full-Stack Developer & Chief Course Artisan - Voitanos LLC.
Andrew Connell is a full stack developer who focuses on Microsoft Azure & Microsoft 365. He’s a 22-year recipient of Microsoft’s MVP award and has helped thousands of developers through the various courses he’s authored & taught. Whether it’s an introduction to the entire ecosystem, or a deep dive into a specific software, his resources, tools, and support help web developers become experts in the Microsoft 365 ecosystem, so they can become irreplaceable in their organization.
