Restructure SharePoint Embedded docs into a task-based, agent-ready information architecture#2
Open
ShreyasSar26 wants to merge 10 commits into
Open
Conversation
Reorganize the SPE doc set around what readers come to do, with a clear developer/admin split and a routing top-level entry point. - Rewrite overview.md as a router to Plan/Build/Publish/Administer/Reference - Add 43 task-based articles across plan/, build/, publish/, admin/, reference/ - Replace the embedded section of toc.yml with the task-based structure - Add llms.txt corpus index for coding agents; add per-article agent metadata - Consolidate the two role-based landing drafts into one task-based index - Split oversized search-content into a focused task article Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Rewrite 8 padded build articles to remove templated filler; embed authoritative archival (Graph beta archive/unarchive, IsArchiveEnabled) and Foundry knowledge-source (containerTypeId, readContent grant) content - Add real container type audit events (ContainerTypeCreated/Deleted/Updated/ OwnersUpdated) and Search-UnifiedAuditLog example to audit articles - Add authoritative install permissions (FileStorageContainerTypeReg.Selected, FileStorageContainer.Selected) and admin-consent URL to publish prep article - Align standard billing cmdlet to two-step New-SPOContainerType + Add-SPOContainerTypeBilling pattern; reconcile ManageContent permission - Mark container type Graph APIs as beta; add principal-owner filter; fix -Identity spacing; remove stale source-pending hedges Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…, task framing - Add visible Next steps / Related resources nav sections to 13 articles - Standardize singular 'Next step' headings to 'Next steps' across 27 articles - Add closing nav + cross-task links to archive-restore-containers.md - Verified: 0 broken links, 46/46 TOC hrefs, llms.txt indexes all 43 articles Audited with automated rubric (4 dimensions x 25 pts): 43/43 articles perfect. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ran an empirical eval: 5 agents restricted to the doc set answered 21 real SPE user queries; graded findability/sufficiency/correctness vs ground truth. Round 1: 21/21 correct, 93.7% quality. Fixed the 4 weak spots and re-tested: - overview.md: add explicit developer-vs-admin role disambiguator (Q21) - container-metadata.md: cross-link to search for free-text/OWSTEXT queries (Q08) - limits-calling-patterns.md: add 'throughput' terminology and limit-increase guidance so agents match the resource-units model (Q11) Round 2: all four queries now Complete with no gaps -> 21/21 at full score. Structure unchanged at 100/100; 0 broken links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Repoint the 'Enable SharePoint Embedded' card to the existing 'Build your first app' quickstart so the SPE entry surface in the SharePoint dev docs hub no longer points at a non-existent page. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Stress-tested the SPE docs with 54 edge-case queries answered by doc-restricted retrieval agents. Closed the gaps they surfaced: - overview: state explicitly that SPE is API-only with no no-code path - limits: clarify trial vs standard container types - security/compliance: clarify container sensitivity-label scope and that files are not retroactively relabeled - manage-files: give the 250 MB simple-upload vs upload-session threshold - search: state search is beta-only (no v1.0 container search) and when to use full-text search vs an OData filter Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document both validation campaigns for training/reproducibility: - structural scorer rubric and 100/100 result - 21-query persona Q&A campaign (two rounds) - 54-query edge-case stress test with full prompts, raw agent outputs, grading, gaps found, fixes applied, and round-2 re-test (162/162) These records live outside docs/ and are not part of the published TOC. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rank 10 developer/admin SPE agent scenarios by customer and product impact, then document the top 5 in full with input prompt, doc-grounded ground truth, a 0/1/2 weighted rubric, scoring bands, and key failure modes: auth/container-type/permission design; Copilot/Foundry agent grounding; enterprise compliance and governance; core document management; and pricing/billing/capacity planning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…-5 SPE tasks Run the top-5 agent scenarios from 06-scenario-evaluations.md against the revamped docs using documentation-restricted explore agents, grade each output against its 10-criterion rubric, and document prompts, output summaries, scoring tables, gaps, and cited files. All five scenarios scored Excellent (A 19, B 20, C 20, D 20, E 19 = 98/100). Agents cited the new task-based plan/build/admin/reference articles as primary sources, confirming the restructure is agent-ready. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… doc structure Document the why and how behind the SPE docs restructure so any agent can reproduce or extend it: governing principles, the six-node task-based IA, the method for deriving tasks, source->target mapping rules, the article authoring contract, router design, llms.txt/TOC wiring, the validation loop, and a reproduction checklist with guardrails. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganizes the SharePoint Embedded (SPE) documentation into a task-based information architecture with a clear developer/admin split, a single routing entry point, and full agent accessibility. The set comprises 43 right-sized task articles plus a router, an agent index (
llms.txt), and an updated TOC.New IA
docs/embedded/overview.md— routing entry point that directs each persona (developer, admin, architect, IT decision maker, billing/compliance admin) to the right task area without forking the experience.plan/(7) ·build/(16) ·publish/(4) ·admin/(10) ·reference/(6) — task articles ordered along the real user journey.llms.txt— task-organized agent index following the llms.txt standard.Principles applied
build/+publish/for app builders;admin/for tenant admins.overview.mdroutes by role/task; secondary personas served without extra forks.<!-- agent: task_type/audience/outcome/next -->block, an**Applies to**line, and a visible Next steps / Related section.Validation
llms.txtindexes all 43 articles, frontmatter YAML valid, no padding/duplicated content.Commits
🤖 Co-authored with GitHub Copilot.