docs: restructure the documentation using the Diataxis framework - #438
Open
sintaxasn wants to merge 14 commits into
Open
docs: restructure the documentation using the Diataxis framework#438sintaxasn wants to merge 14 commits into
sintaxasn wants to merge 14 commits into
Conversation
Two learning-oriented lessons that take a reader from nothing to a working deployment: - Your first deployment: install the module, generate a template, package and run a silent install. - Adding a user experience: extend that deployment with the Welcome dialog, a progress dialog, deferrals and a restart prompt. Tutorials are the first of the four Diataxis categories being introduced; the remaining sections follow.
Replaces the Usage pages and two Getting Started pages with goal-oriented guides: - Install the toolkit (was getting-started/download) - Create a deployment (was getting-started/creating-a-new-deployment) - Run a deployment (was usage/how-to-deploy) - Deploy an MSI with zero-config - Install applications (was usage/installing-applications) - Customize a deployment (was usage/customizing-deployments) Each guide now answers a single question rather than mixing tutorial, reference and explanation in one page.
Replaces usage/adding-ui-elements with two focused guides: - Brand the user interface: dialog style, logo, banner and accent colour. - Close apps and allow deferral: the Welcome dialog, close countdowns and deferral limits. Screenshots of the dialogs described here live in reference/dialogs.
Documents packaging and distribution through each management platform, which the old docs only covered indirectly through the examples section: - Deploy with Intune: .intunewin packaging, install and uninstall commands, detection rules and exit code mapping. - Deploy with Configuration Manager: application model, deployment types and detection methods. - Deploy Google Chrome with Configuration Manager: worked end-to-end example (was examples/googlechrome-configmgr).
Replaces usage/admx-templates and examples/admxtemplate-LogPath: - Configure the toolkit with Group Policy: importing the ADMX and ADML files and where the resulting settings land in the registry. - Set the log path with Group Policy: worked example of overriding a single setting centrally.
- Upgrade from v3 (was getting-started/upgrade-guidance-v3x-to-v41) - Upgrade from v4.0 (was getting-started/upgrade-guidance-4x-to-v41) - Extend the toolkit with custom functions - Troubleshoot a deployment The upgrade pages keep their content but are reframed as tasks rather than release guidance, and now sit alongside the other how-to guides.
The old Deployment Concepts pages mixed background with instructions. The new Explanation section covers understanding only, and points at the how-to guides for the steps: - Architecture: module, session, dialogs and the compiled assemblies. - The deployment script: what Invoke-AppDeployToolkit.ps1 does and why it is structured in phases (was deployment-concepts/invoke-appdeploytoolkit). - Deployment modes: interactive, silent and non-interactive, and how the mode is chosen (was deployment-concepts/deployment-structure). - User interface: Classic and Fluent, and the role of each dialog. - Configuration: how built-in defaults, config.psd1 and Group Policy combine. - Logging: log types, locations and what ends up in each. Zero-config deployment moves to a how-to guide, added earlier in this branch.
Requirements, licensing, release notes and the FAQ are look-up material rather than a starting path through the docs, so they belong in reference. Content is unchanged apart from frontmatter; the existing slugs are kept so external links still resolve. This empties and removes the Getting Started section.
Material that was previously scattered through the usage pages, or only available by reading the template, now has a page of its own: - Command-line parameters: every parameter accepted by Invoke-AppDeployToolkit.ps1. - Deployment template: the files in a generated template and what each is for. - Dialogs: each dialog, its parameters and its Classic/Fluent differences. - Process execution: Start-ADTProcess and Start-ADTMsiProcess parameters, exit code handling and the process family. - Troubleshooting: symptoms, causes and diagnostics in table form.
- Repoint links that referred to getting-started, usage, examples and deployment-concepts at their new locations. - Replace release-note phrasing such as "Default changed to" in config-settings with statements of current behaviour, since the page documents the settings rather than the release. - Refresh descriptions and sidebar positions so the reference sidebar reads in a sensible order.
Presents the docs sidebar as Tutorials, How-to Guides and Explanation, with Reference kept in its own sidebar, and adds a short description to each generated category index so the purpose of each section is stated where a reader lands. The introduction and reference landing pages are rewritten to point at the new sections and to explain which one to read for which kind of question.
- framer-motion 12.42.2 -> 13.1.0 - eslint 9.39.0 -> 10.8.1 - typescript 6.0.3 -> 7.0.2 - @easyops-cn/docusaurus-search-local 0.55.2 -> 0.55.3 - @types/node 26.1.0 -> 26.2.0 - @types/react 19.2.17 -> 19.2.18 - @typescript-eslint/eslint-plugin 8.63.0 -> 8.67.0 - @typescript-eslint/parser 8.63.0 -> 8.67.0 - prettier 3.9.4 -> 3.9.6
Captured from a real deployment against PSAppDeployToolkit 4.2.0, all three from the same package so the only difference between them is the setting being illustrated: - welcomedialog_fluent: the Welcome dialog in the Fluent style, with the default logo and accent colour. - welcomedialog_classic: the same dialog with UI.DialogStyle set to Classic. - welcomedialog_branded: the Fluent dialog with Assets\AppIcon.png replaced and FluentAccentColor set, to show what branding changes. The explanation page now shows the two styles beside their descriptions, and the branding how-to shows default and branded side by side under Check the result.
Captures 13 dialog configurations from a real deployment against PSAppDeployToolkit 4.2.0, each shot twice so the light image is shown to readers in light mode and the dark image in dark mode via ThemedImage. Tutorials: - Your first deployment gains the progress dialog and the completion prompt, so the reader can check what they should be seeing. - Adding a user experience gains the welcome dialog listing Notepad with three deferrals remaining, the same dialog with no Defer button, and the progress dialog mid-install showing the detail line and the bar at 75%. Explanation: - The user interface page shows the Fluent dialog as a theme-swapping image, which demonstrates the light and dark support the text claims, and gains the same dialog rendered in German as evidence for the localization section. - Deployment modes shows the progress dialog as the one thing NonInteractive still allows. How-to guides: - Closing apps and allowing deferral gains the defer-only dialog and the countdown mid-count. - Branding moves to theme-aware images for the default and branded comparison. - Troubleshooting gains the help console. Reference: - Text formatting renders the Office 365 markup example the page already quotes. The page previously described five formatting tags without showing what any of them produce. The Classic dialogs are out of scope, so the Classic screenshot added earlier in this branch is removed rather than paired with a dark variant. Images are cropped to the DWM extended frame bounds, which excludes the window's drop shadow, and carry no margin; the existing .markdown_image class supplies the shadow and corner radius as it does for every other image in the docs.
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
Reorganises the documentation into the four Diataxis categories, so that each page has one job instead of four.
The old sections (
getting-started,usage,deployment-concepts,examples) mixed teaching, instructions, background and specification on the same page. That made pages hard to scan, and it left gaps: nothing owned command-line parameters, the deployment template, or process execution, so those were documented only in passing or not at all.The commits are split by section, so they can be reviewed one at a time.
Structure
Tutorials are new. There are two, and they run in order: build a working deployment from nothing, then give it a user experience with dialogs, deferral and progress reporting.
How-to guides replace
usageandexamples. Seventeen of them, each answering one question: install the toolkit, create a deployment, run one, deploy an MSI with zero-config, install applications, customize a deployment, brand the interface, close apps and allow deferral, deploy with Intune or Configuration Manager, deploy Google Chrome with Configuration Manager, configure with Group Policy, set the log path with Group Policy, extend the toolkit with custom functions, troubleshoot a deployment, and upgrade from v3 or v4.0.Explanation replaces
deployment-conceptsand covers the reasoning: architecture, the deployment script, deployment modes, the user interface, configuration and logging. These pages explain why the toolkit behaves as it does, and hand off to the how-to guides for the steps.Reference gains pages for command-line parameters, the deployment template, dialogs, process execution and troubleshooting. Requirements, licensing, release notes and the FAQ move here from
getting-started, which no longer exists. The existing reference pages are updated for the new link structure.sidebars.jsis rebuilt around the same shape, with tutorials, how-to guides and explanation in the docs sidebar and reference in its own. The introduction and reference landing pages are rewritten to say which section answers which kind of question.Screenshots
Thirteen dialog configurations were captured from a real deployment against 4.2.0, each shot in both themes and wired up with
ThemedImage, so the light capture is shown to readers in light mode and the dark one in dark mode.Some of these fill real gaps. The text formatting reference described five markup tags without showing what any of them produce, and now renders the Office 365 example the page already quoted. The user interface page claimed light and dark support, and now demonstrates it as the reader toggles the site. It also claimed the dialogs ship translated into 25 languages, and now shows the same dialog in German.
Every image comes from the same sample package, so the docs read as one product rather than several. Images are cropped to the DWM extended frame bounds, which excludes the window's drop shadow, and carry no margin; the existing
.markdown_imageclass supplies the shadow and corner radius as it does for every other image.The Classic dialogs are deliberately not pictured.
Not included
The balloon notification on the dialogs reference has no screenshot.
Show-ADTBalloonTipruns without error, but Windows notifications are disabled on the machine the captures were taken on, so no toast is ever raised. Worth a follow-up from a machine with notifications on.The fifteen existing images on the dialogs reference are also untouched. They came from an earlier build and use a different sample application and branding from everything else here, so recapturing them would be worth doing, but it is a replacement rather than an addition and did not belong in this change.
Compatibility
The moved pages keep their existing slugs (
/getting-started/requirements,/getting-started/licensing,/getting-started/release-notes,/getting-started/faq), so external links to them still resolve.Dependency updates are in their own commit at the end.
Testing
pnpm buildpasses.onBrokenLinksis set tothrow, so every internal link across the moved and rewritten pages resolves.