docs: restructure the documentation using the Diataxis framework - #438
Open
sintaxasn wants to merge 16 commits into
Open
docs: restructure the documentation using the Diataxis framework#438sintaxasn wants to merge 16 commits into
sintaxasn wants to merge 16 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.
Rebuilds the dialogs reference around what each dialog can be asked to do, rather than showing one example of each and leaving the parameters to the function pages. Adds thirteen configurations, each captured in light and dark against PSAppDeployToolkit 4.2.0: - Welcome with a deferral deadline and an automatic start countdown at the same time, which is the combination most estates end up running. - Installation prompt with one, two and three buttons, with an input field, with that field pre-filled by -DefaultValue, with -SecureInput, and with -ListItems. - Restart prompt with -NoCountdown, with -Countdown, and with -CountdownNoHide. - Dialog box with OK/Cancel and with Yes/No/Cancel. The older dialog screenshots are left in place: versioned_docs for 4.1.x, 4.0.x and 3.10.2 still reference them.
Mostly just to get that CodeQL action to re-run successfully.
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
2 participants
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 left gaps as well as clutter. Nothing owned command-line parameters, the deployment template or process execution, so those were documented in passing or not at all.The commits are split by section, so they can be reviewed one at a time.
Structure
The tutorials are new. They are meant to be worked through in order: the first builds a deployment that installs an MSI, the second gives it a user experience with dialogs, deferral and progress reporting.
usageandexamplesare gone, replaced by how-to guides that each answer a single question. They run from installing the toolkit, through packaging for Intune and Configuration Manager, to upgrading a v3 package.deployment-conceptsbecomes explanation: architecture, the deployment script, deployment modes, the user interface, configuration and logging. These pages say why the toolkit behaves as it does, and hand off to the how-to guides for the steps.Reference picks up the material that previously had nowhere to live, including 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.sidebars.jsfollows the same shape, and the introduction and reference landing pages now say which section answers which kind of question.Screenshots
Every dialog screenshot was captured from a real deployment against 4.2.0, using one sample package throughout.
In Reference > Dialogs, there are screenshots for each dialog variation. For the welcome dialog that means applications to close, deferral on its own, a close countdown, and a deferral deadline running alongside an automatic start countdown. The installation prompt appears with one, two and three buttons, with an input field, with that field pre-filled, with masked input, and with a list to choose from. All three restart variants are covered, as are both message box shapes.
Screenshots are shown in light or dark mode, depending on which you have set (changeable in the top right hand corner of the website).
Not included
The balloon notification has no screenshot. Windows draws it rather than the toolkit, and no toast is raised on the machine the captures came from.
The Classic dialogs are deliberately not pictured.
Compatibility
The moved pages keep their existing slugs (
/getting-started/requirements,/getting-started/licensing,/getting-started/release-notes,/getting-started/faq), so external links still resolve.The older dialog screenshots stay in the repository.
versioned_docsfor 4.1.x, 4.0.x and 3.10.2 still reference them.Dependency updates are in their own commit.
Testing
pnpm buildpasses.onBrokenLinksis set tothrow, so every internal link across the moved and rewritten pages resolves.