Scan Details - Linux-first Docs for Azure

1123

Pages Scanned

Pages Flagged

1123

Changed Pages

0.4%

% Pages Flagged

Scan Information

Started At: 2025-07-22 00:01:03

Finished At: 2025-07-22 00:05:00

Status: completed

Target URL: https://github.com/MicrosoftDocs/azure-docs/tree/main/articles

Current Phase: discovery

Problematic Pages

Bias Types:

⚠️ powershell_heavy

⚠️ windows_first

⚠️ missing_linux_example

⚠️ windows_tools

Summary:

The documentation page demonstrates a Windows bias by providing only Azure PowerShell command-line examples for scripting and automation, with no equivalent examples for Azure CLI (which is cross-platform and more commonly used on Linux/macOS). The PowerShell approach is introduced before any mention of ARM templates, and there are no Linux-native or bash shell examples. The installation instructions and sample code reference Windows-centric tools and patterns, omitting Linux-friendly alternatives.

Recommendations:

Add Azure CLI examples alongside all Azure PowerShell examples, especially for creating and managing managed identities and API Management instances.
When introducing command-line automation, present Azure CLI before or alongside PowerShell to avoid Windows-first ordering.
Explicitly mention that both Azure CLI and PowerShell are supported, and link to cross-platform installation guides.
Include bash shell scripting examples where appropriate, or at least note that all CLI commands work in Linux/macOS terminals.
Where possible, provide parity in screenshots and UI instructions for Linux/macOS users (for example, referencing Azure Cloud Shell, which is cross-platform).

Create pull request

Bias Types:

⚠️ powershell_heavy

⚠️ windows_first

⚠️ missing_linux_example

Summary:

The documentation page demonstrates a Windows bias in its automation section by providing a PowerShell script example but omitting a corresponding Linux shell (Bash) example. The scripting section lists Azure CLI and PowerShell, but only the PowerShell script is shown inline, while the Azure CLI is linked. There are no explicit Linux/Bash command examples, and the PowerShell example is given more prominence. The rest of the documentation is largely platform-neutral, but the automation section prioritizes Windows tooling.

Recommendations:

Provide a Bash shell script example for Linux users alongside the PowerShell example in the automation section.
Show both Azure CLI and PowerShell scripts inline, or at least give them equal prominence.
Explicitly mention that the Azure CLI commands work cross-platform (Windows, Linux, macOS) to encourage Linux usage.
Where scripting is referenced, ensure parity by including both Windows and Linux command-line approaches.
Consider adding a note or section for Linux users, especially in automation contexts, to improve inclusivity.

Create pull request

Bias Types:

⚠️ windows_first

⚠️ missing_linux_example

Summary:

The documentation demonstrates a 'windows_first' bias by providing detailed ASP.NET Core and ASP.NET Web Forms (Windows-centric) code samples before other platforms. There are no explicit Linux command-line or configuration examples (e.g., for Apache/Nginx, OpenSSL, or Linux shell), and the focus is on .NET/Windows patterns. While Node.js, Java, and Python samples are included, there is no guidance for Linux-specific TLS mutual authentication setup or validation outside the Azure App Service context.

Recommendations:

Add Linux-native command-line examples (e.g., using OpenSSL, curl, or wget) to demonstrate client certificate creation, validation, and testing.
Include guidance or references for configuring mutual TLS in common Linux web servers (e.g., Nginx, Apache) when running on App Service for Linux.
Provide parity in code samples by including examples for popular Linux-first frameworks (e.g., FastAPI, Go, Ruby on Rails) and shell scripting.
Clarify that the .NET examples are cross-platform, or provide explicit instructions for running them on Linux if applicable.
Ensure that any tool or UI references (such as Azure CLI) are shown with both Windows and Linux shell syntax where differences exist.

Create pull request

Bias Types:

⚠️ windows_first

⚠️ missing_linux_example

Summary:

The documentation primarily uses platform-agnostic instructions but contains a subtle Windows bias in the troubleshooting section, where only the Windows command (ipconfig /flushdns) is provided for clearing the DNS cache. No equivalent Linux or macOS commands are mentioned. There are no PowerShell-heavy sections or exclusive references to Windows tools, but the absence of cross-platform examples in this context may disadvantage Linux/macOS users.

Recommendations:

When suggesting clearing the DNS cache, include equivalent commands for Linux (e.g., 'sudo systemd-resolve --flush-caches' or 'sudo service nscd restart') and macOS (e.g., 'sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder').
Review all troubleshooting steps and ensure platform parity by providing instructions for Windows, Linux, and macOS where applicable.
Consider adding a short note or table summarizing common DNS cache flush commands for all major operating systems.

Create pull request

Bias Types:

⚠️ windows_first

⚠️ powershell_heavy

Summary:

The documentation provides both Azure CLI and PowerShell examples for exporting App Service certificates, but the PowerShell example is given its own dedicated section, and a specific FAQ addresses PowerShell usage. There are no Linux-specific tools or shell examples (e.g., bash, OpenSSL), and the CLI instructions, while cross-platform, are not explicitly labeled as Linux-friendly. The overall structure and examples may give the impression of a Windows-first or PowerShell-preferred workflow.

Recommendations:

Add explicit Linux/macOS shell (bash) examples for certificate export, including using OpenSSL to handle .pfx files.
Clarify that Azure CLI commands are cross-platform and can be run on Linux, macOS, and Windows.
Include troubleshooting or FAQs for Linux users, such as handling .pfx files or installing certificates on Linux-based systems.
When presenting multiple command-line options, consider listing Azure CLI (cross-platform) before PowerShell to avoid a Windows-first impression.
Mention common Linux tools (e.g., keytool, OpenSSL) where relevant, especially in sections about certificate export and installation.

Create pull request

No problematic pages found in this scan. All pages appear to be Linux-friendly! 🐧