copilot-instructions.md

Project Overview

This project is a collection of "Learning Paths" (long-form tutorials) and "install guides" (shorter software installation guides), hosted on a static website using Hugo and markdown files. The content explains how to develop software on Arm for software developers targeting various Arm platforms.

Assume the audience is made up of Arm software developers. Bias all information toward Arm platforms. For Linux, assume systems are aarch64 architecture and not x86. Readers also use macOS and Windows on Arm systems, and assume Arm architecture where relevant.

Highest priority rules

• One Learning Path must own one clear developer task
• Install guides are for installation and verification only
• Every Learning Path _index.md must include a description field
• Use task-led titles, introductions, and metadata
• Do not use placeholder alt text such as alt-txt
• Prefer Arm-native solutions and Arm-specific framing
• Avoid hype, duplication, and vague summaries

Project structure

The key directories are:

Top-level structure

• /content - The main directory containing all Learning Paths and install guides as markdown files
• /themes - HTML templates and styling elements that render the content into the final website
• /tools - Python scripts for automated website integrity checking
• config.toml - High-level Hugo configuration settings

Content organization

The /content directory is organized into:

• learning-paths/ - Core learning content organized by categories:

  • embedded-and-microcontrollers/ - MCU, IoT, and embedded development topics
  • servers-and-cloud-computing/ - Server, cloud, and enterprise computing topics
  • mobile-graphics-and-gaming/ - Mobile app development, graphics, and gaming
  • cross-platform/ - Cross-platform development and general programming topics, these appear in multiple categories on the website
  • laptops-and-desktops/ - Desktop application development, primarily Windows on Arm and macOS
  • automotive/ - Automotive and ADAS development
  • iot/ - IoT-specific Learning Paths

• install-guides/ - Tool installation guides with supporting subdirectories organized by tool categories like docker/, gcc/, license/, browsers/, plus an _images/ directory for screenshots and diagrams

These are special directories and not used for regular content creation:

• migration/ - Migration guides and resources, this maps to https://learn.arm.com/migration
• lists/ - Content listing and organization files, this maps to https://learn.arm.com/lists
• stats/ - Website statistics and analytics, this maps to https://learn.arm.com/stats

The /content directory is the primary workspace where contributors add new Learning Paths as markdown files, organized into category-specific subdirectories that correspond to the different learning path topics available on the site at https://learn.arm.com/.

Content requirements

Read the files in the directory content/learning-paths/cross-platform/_example-learning-path for information about how Learning Path content should be created. Also see the guidelines below.

• Learning Paths: use for end-to-end tasks (prepare → configure → use → validate). Must include _index.md and _next-steps.md
• Install guides: use for installation + verification only. Do not include workflow content or benchmarks

Content structure

Each Learning Path must have an _index.md file and a _next-steps.md file. The _index.md file contains the main content of the Learning Path. The _next-steps.md file contains links to related content and is included at the end of the Learning Path.

Additional resources and next steps content should be placed in the further_reading section of _index.md, not in _next-steps.md. The _next-steps.md file should remain minimal and unmodified as indicated by FIXED, DO NOT MODIFY comments in the template.

The _index.md file should contain the following front matter and content sections.

Front matter (YAML format)

• title: Imperative heading following the [verb] + [technology] + [outcome] format
• description: One-sentence metadata summary used for search snippets and page previews. Describe the task, main technology or platform, and expected outcome in plain language
• weight: Numerical ordering for display sequence, weight is 1 for _index.md and each page is ordered by weight, no markdown files should have the same weight in a directory
• layout: Template type (usually "learningpathall")
• minutes_to_complete: Realistic time estimate for completion
• prerequisites: List of required knowledge, tools, or prior learning paths
• author: Main contributor's name, multiple authors can be listed separated using - on new lines
• subjects: Technology categories for filtering and search, this is a closed list and must match one of the subjects listed on https://learn.arm.com/learning-paths/cross-platform/_example-learning-path/write-2-metadata/
• armips: Relevant Arm IP, stick to Neoverse, Cortex-A, Cortex-M, etc. Don't list specific CPU models or Arm architecture versions
• tools_software_languages: Open category listing Programming languages, frameworks, and development tools used
• skilllevels: Skill levels allowed are only Introductory and Advanced
• operatingsystems: Operating systems used, must match the closed list on https://learn.arm.com/learning-paths/cross-platform/_example-learning-path/write-2-metadata/

Install guide requirements

Install guides focus on installing and verifying one tool on Arm platforms. They do not teach workflows or applied usage.

Front matter requirements

Install guides must include:

• title
• minutes_to_complete
• official_docs
• author
• weight: 1
• layout: installtoolsall

Fixed fields for install guides

• weight: 1 (always)
• tool_install: true (set to false only if intentionally hidden)
• layout: installtoolsall (always)
• multi_install and multitool_install_part (set based on whether the install guide is multi-page)

Do not modify fixed template fields.

If multi_install is set to true, the first page must act as an overview for the series. Sub-pages must set multitool_install_part: true.

Required content structure

Install guides should include:

1. Overview

   • What the tool is
   • Supported Arm platforms (aarch64, Windows on Arm, macOS on Arm where applicable)

2. Install steps

   • Clear OS-specific sections when necessary
   • Commands grouped logically
   • Explanation before each code block

3. Verify installation

   • One or two commands
   • Expected output shown

4. Troubleshooting

   • Common failure cases
   • Clear fixes

Optional:

• Uninstall instructions

Scope boundaries

Install guides must not include:

• End-to-end workflows
• Performance benchmarking
• Deep architectural explanation
• Comparative marketing claims

Learning Paths may link to install guides for setup steps. Install guides should not duplicate workflow content.

Further reading curation

Limit further_reading resources to four to six essential links. Prioritize:

• Direct relevance to the topic
• Arm-specific Learning Paths over generic external resources
• Foundation knowledge for the target audience
• Required tools (install guides)
• Logical progression from basic to advanced

Avoid overwhelming readers with too many links, which can cause them to leave the platform.

All Learning Paths should generally include:

• Title: [Imperative verb] + [technology/tool] + [outcome]
• Introduction paragraph: Context + user goal + value proposition
• Prerequisites section with explicit requirements and links
• Learning objectives: three to four bulleted, measurable outcomes with action verbs
• Step-by-step sections with logical progression
• Clear next steps or conclusion

For title formatting:

• Must use imperative voice (Deploy, Configure, Build, Create)
• Must include SEO keywords (technology names, tools)
• Examples: Deploy applications on Arm servers, Configure Arm processors for optimal performance

The term "Learning Path" should always be capitalized.

Metadata descriptions

Learning Path metadata description requirements

Every Learning Path _index.md must include a description field.

• Write one sentence
• Describe the task, the main technology or platform, and the expected outcome
• Keep it concise, developer-focused, and suitable for use as a search snippet
• Use a task-led structure such as: Verb + task + tool/platform + outcome
• Do not repeat the title verbatim
• Do not use vague summaries or marketing language
• A slightly richer one-sentence summary is acceptable when it helps clarify the workflow or outcome

Good example:

description: Learn how to automate x86-to-Arm application migration using the Arm MCP Server, with compatibility checks and Docker-based validation on Arm cloud platforms.

Also good:

description: Learn how to profile and optimize a C++ application on Arm Neoverse using Arm Performix to identify bottlenecks and improve runtime.

Avoid:

• Generic summaries that could apply to any page
• Restating the title without adding task or outcome
• Marketing phrases such as powerful, cutting-edge, or game-changing

Metadata optimization workflow

When adding or revising description fields:

• Review whether the current title and description match the page's actual task intent
• Use metadata descriptions to clarify what the learner will do, on which platform or tool, and with what outcome
• Treat the description as a search snippet, not a generic summary

Writing style

Voice and tone

• Second person (you, your) — never first person (I, we)
• Active voice — avoid passive constructions
• Present tense for descriptions
• Imperative mood for commands
• Confident and developer-friendly tone
• Encouraging language for complex tasks
• Use inclusive language:
  • Use primary/subordinate instead of master/slave
  • Do not use gendered examples or assumptions
  • Be mindful of cultural references that might not translate globally
  • Focus on clear, accessible language for all developers

Sentence structure and clarity

• Average 15–20 words per sentence
• Split complex sentences for clarity
• Use plain English and avoid jargon overload
• Use US spellings (organize, optimize, realize)
• Use Arm capitalization in prose (Arm processors, Arm servers, Neoverse)
• arm64 and aarch64 are permitted in code, commands, and outputs
• Define acronyms on first use
• Use parallel structure in all lists

Readability and section flow

• Flag any section over 700 words and suggest natural split points
• Warn if more than 300 words appear between code examples
• Identify paragraphs with sentences averaging over 20 words
• Note sections introducing more than two new concepts
• Flag pages over 3500 words total
• Note sections that might benefit from encouragement or progress markers
• Identify missing celebration of progress or milestones
• Recap what learners have accomplished at section ends
• Provide check-your-understanding moments that are not intimidating
• Use visual breaks to prevent walls of text. Code blocks count as visual breaks
• If you explain three or more things in one section, split it into separate sections
• Each code block should be preceded by one to three sentences explaining what it does
• For Learning Paths, include a short recap and forward-looking transition at the end of each major instructional section or module

Example recap pattern for Learning Paths:

## What you've learned and what's next

In this section:
- Briefly summarize what the user has learned or completed
- Briefly describe what the user should expect in the next section or suggest further exploration

Keep this concise and encouraging. Do not repeat earlier content verbatim.

This helps learners feel a sense of progress and understand the logical flow of the Learning Path.

Word choice and style

Use these preferred terms and phrases for consistency:

• Numbers and units:

  • Spell out numbers one through five. After that, use numerals
  • Use proper spacing for units: 1 GB, 23 MB/day
  • Use K for thousands: 64K
  • Use abbreviations for data rates: Gbps

• Common phrases:

  • To [action] instead of Follow the steps below to [action]
  • for example instead of e.g.
  • that is instead of i.e.
  • because instead of since
  • also instead of in addition
  • to instead of in order to
  • see instead of refer to
  • use instead of utilize or leverage
  • need instead of require
  • can or might instead of may
  • set up as a verb, setup as a noun
  • therefore instead of ergo
  • namely instead of viz.
  • avoid instead of try not to

• Avoid condescending language:

  • Do not use simply, just, obviously, or clearly

• Acknowledge difficulty naturally:

  • Use phrases like this step can be confusing at first

• Normalize errors:

  • Use phrases like if you see this error, here's how to fix it

• User interface terms:

  • select or tap instead of click for touch interfaces
  • keyboard shortcut instead of key combination
  • Ctrl key capitalized
  • double-tap instead of double-click for touch interfaces

• Contractions and simplification:

  • Use contractions such as don't, isn't, it's, that's, you're, you'll
  • Remove unnecessary qualifiers such as quite, very, or massive
  • Use an LLM, not a LLM
  • Use easy-to-use as an adjective
  • Use fixed-width, not fixed-length
  • Use read-to-write ratio, not read to write ratio

Content structure and consistency

Cross-file and quality assurance

• Use the same technical terms consistently throughout all sections
• Apply the word choice and style guidelines uniformly across all files
• Maintain consistent capitalization of product names, technologies, and concepts
• Use the same abbreviations and acronyms throughout
• Maintain the same voice and tone across all sections
• Ensure consistent use of second person throughout
• Apply the same level of formality and technical depth across sections
• Keep instructional style consistent
• Follow consistent heading hierarchy throughout the Learning Path
• Use parallel structure in similar sections across different files
• Maintain consistent section organization and flow
• Apply uniform formatting for code blocks, lists, and callouts
• Ensure appropriate skill level consistency
• Maintain consistent technical detail appropriate for the target audience
• Balance complexity appropriately across all sections
• Provide consistent prerequisite assumptions throughout
• Flag inconsistent terminology usage across sections
• Identify missing error handling or troubleshooting guidance
• Suggest where visual aids would improve understanding
• Recommend splitting overly complex sections
• Verify that code examples follow established patterns in the repository

Formatting and code samples

Heading guidelines

• Use sentence case for all headings

• Heading types:

  • Conceptual headings: when explaining technology or motivation
  • Imperative headings: when the user takes action
  • Interrogative headings: for FAQ content

• Hierarchy:

  • H1: Page title
  • H2: Major workflow steps or conceptual sections
  • H3: Sub-procedures or detailed explanations
  • H4: Specific technical details or troubleshooting

Heading hierarchy and section openings

• Check heading hierarchy across all files before finalizing content
• Ensure headings follow a logical structure with no skipped levels unless the template requires it
• Each markdown file should begin with a section heading in the body content
• Do not leave a file starting with body text, an image, or a code block without a heading
• Use sentence case for all headings and subheadings
• Capitalize only the first word and proper nouns in headings
• Keep heading wording consistent across related files in the same Learning Path
• Prefer headings that clearly signal the user task or concept in that section

Correct examples:

• ## Set up the environment
• ## Run the benchmark
• ### Check the output
• ## What you've accomplished and what's next

Avoid:

• ## Set Up The Environment
• ## RUN THE BENCHMARK
• starting a file with plain paragraph text and no heading

Code samples and formatting

• Always provide explanation before code blocks
• Format: [What it does] → [Code] → [Expected outcome] → [Key parameters]
• Use markdown tags for languages like bash, python, yaml, json
• Use console or bash for general commands. Try to use the same one throughout a Learning Path
• Use the output tag to show expected command output
• Output descriptions:
  • Use The output is similar to: or The expected output is:
  • Use present tense descriptions such as builds and gives
• Formatting standards:
  • Bold for UI elements
  • Italics for emphasis and new terms
  • Code formatting for file names, commands, and code elements
• Use shortcodes for common pitfalls, warnings, and important notes

Code fence integrity

• Every fenced code block opened with triple backticks must be explicitly closed with matching triple backticks before any non-code content resumes
• Never generate unterminated or partial code fences
• Do not rely on implicit closure, indentation, or surrounding formatting to end a code block

Arm naming and architecture terms

• Use Arm for the brand in prose
• Use arm64 or aarch64 for the CPU architecture. Prefer whichever term a tool, package, or OS uses natively
• Always use Arm rather than ARM in prose unless a technical term requires the original casing
• ARM64 is acceptable when specifically referring to Windows on Arm or Microsoft documentation
• In code blocks, CLI flags, package names, file paths, and outputs, keep the exact casing used by the tool

Product name emphasis

• Product names and technologies such as LiteRT, XNNPACK, KleidiAI, and SME2 should appear in regular text
• Avoid using italics or bold to emphasize product or technology names unless they are part of a heading or a UI label

Hyperlink guidelines

• Use the full path format for internal links: /learning-paths/category/path-name/
• Do not use relative paths like ../path-name/
• Use the full URL for external links that are not on learn.arm.com
• When creating Learning Path content:
  • Verify internal links exist before adding them
  • Use semantic search or website browsing to confirm Learning Path availability
  • Prefer verified external authoritative sources over speculative internal links
  • Test link formats against existing Learning Path examples
  • Never assume Learning Paths exist without verification
• Include only necessary links in content. For Learning Paths, put additional links in further_reading in _index.md, not _next-steps.md

Avoid looking like AI-generated content

• Warning signs of over-bulleting:

  • More than three consecutive sections using bullet lists
  • Bullet points that could be combined into narrative paragraphs
  • Lists where items do not have parallel structure
  • Bullet points that are actually full sentences better suited for paragraphs

• Use flowing narrative instead of excessive bullets

• Use natural writing patterns:

  • Vary sentence length
  • Use transitional phrases
  • Include contextual explanations
  • Add relevant examples
  • Connect ideas logically

• Use conversational elements naturally:

  • Instead of Execute the following command:, use Now that you've configured the environment, run the following command to start the service:
  • Instead of This provides benefits:, use You'll notice several advantages with this approach, particularly when working with...

Language smoothing

Avoid robotic or generic encouragement phrases such as:

• Great job — let’s get started!
• Great job — your environment is ready!

Use calm, natural transitions that focus on what happens next.

Also avoid multiple consecutive sentences starting with This. Vary sentence structure to maintain natural flow.

AI-specific guidelines for content creation and editing

Context awareness

• Consider the learner's likely environment (development vs. production, local vs. cloud)
• Recognize when content assumes x86 defaults and suggest Arm alternatives
• Flag when third-party tools may have limited Arm support
• Suggest Arm-native alternatives when available

Technical depth consistency

• Maintain appropriate complexity level throughout the Learning Path
• Avoid oversimplifying for Advanced skill level content
• Do not assume prior knowledge beyond stated prerequisites
• Balance theoretical explanation with practical implementation

Platform-specific considerations

• Default to Arm-optimized solutions and configurations
• Mention x86 alternatives only when Arm solutions do not exist
• Consider performance implications specific to Arm architectures
• Address common Arm migration challenges when relevant

Accessibility and inclusivity

• Ensure content is screen reader compatible
• Provide descriptive alt text for images and diagrams
• Use clear, descriptive link text
• Avoid assumptions about the user's physical capabilities or setup

Image formatting, alt text, and captions

In this repository, the text before #center in an image tag is the alt text.

Use this format:

![Descriptive alt text#center](image.png "Optional caption")

Rules:

• Do not use placeholder values such as alt-txt, alt text, or similar
• Do not wrap alt text in extra quotation marks inside []
• Keep #center attached directly to the alt text with no extra space before it
• The caption is optional and should be short, descriptive, and natural
• Avoid outdated figure numbering such as Figure 1: unless the content genuinely depends on numbered cross-references

Correct:

![Diagram showing the WebGPU rendering flow for drawing a triangle#center](images/webgpu-draw-high-level.svg "WebGPU rendering flow for drawing a triangle")

Incorrect:

!["Triangle using WebGPU" #center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU")

Incorrect:

![alt-txt#center](images/webgpu-draw-high-level.svg "Figure 8: Triangle using WebGPU")

Alt text requirements for tutorials

Learning Paths and install guides are instructional content. Images are usually not decorative. Alt text must help the learner understand what they would otherwise miss.

For every image, alt text should explain:

• What is shown
• What the learner should notice
• Why it matters in the current step

For screenshots:

• Name the screen, tool, or interface shown
• Mention the relevant UI element, tab, field, button, or output
• Explain what the learner should look for in the screenshot
• Connect the image to the current step or expected result

For diagrams:

• Describe the components and relationships shown
• Explain the purpose of the diagram in the current task
• Focus on the workflow, architecture, or sequence the learner needs to understand

For terminal or output images:

• State what command result or status is shown
• Highlight the important confirmation, value, or error message
• Explain why that output matters

For hardware images:

• Describe the device or setup only if it helps the learner complete the task
• Avoid purely decorative descriptions

Alt text quality rules

• Write meaningful alt text, not placeholders
• Keep it concise but complete. One to three sentences is usually enough
• Prefer instructional value over visual detail
• Include visible text only when the learner needs that text
• Do not use captions as a substitute for alt text
• Do not encode alignment instructions inside the caption

Caption guidance

• Use short, descriptive captions when needed
• Captions should add context for all readers
• Avoid Figure X numbering unless explicit image cross-references are required

Preferred example:

![Screenshot of the Arm Performance Studio timeline showing CPU activity spikes during Mandelbrot rendering. The Timeline tab is selected and the spike region is highlighted so the learner can identify where CPU activity increases during the run.#center](images/timeline-spike.png "Arm Performance Studio timeline showing CPU activity during Mandelbrot rendering")

Image and metadata cleanup workflow

• Replace all placeholder alt text such as alt-txt with meaningful descriptions
• Keep the repository-specific #center syntax when fixing alt text
• Do not remove valid alignment syntax during cleanup
• Add or improve metadata descriptions systematically across content
• For bulk cleanup, update the guidance first, then fix content by category or directory in manageable batches

SEO and discoverability

• Use Arm-specific keywords naturally throughout content
• Include relevant technical terms that developers search for
• Optimize titles and headings for search engines
• Use semantic HTML structure in markdown when possible
• Consider how content will appear in search results

Cross-reference validation

• Verify all internal links point to existing content
• Check that referenced Learning Paths and install guides are current
• Ensure cross-references between sections remain accurate after edits
• Flag broken or outdated external links
• Maintain consistency in how related content is referenced

Performance testing guidance

• Include benchmarks when comparing Arm vs. x86 performance
• Suggest performance testing steps for resource-intensive applications
• Recommend profiling tools that work well on Arm platforms
• Include guidance on measuring and optimizing for Arm-specific performance characteristics
• Mention when performance improvements are architecture-specific
• Applies to Learning Paths only. Install guides must not include benchmarking

AI optimization (AIO) guidance

• Structure content with clear, semantic headings that AI can parse and understand
• Use descriptive, standalone sentences that make sense without surrounding context
• Include explicit problem statements and clear solutions for AI to reference
• Format code examples with proper language tags and clear explanations
• Use consistent terminology that AI systems can reliably associate with Arm development
• Include complete, self-contained examples rather than partial snippets
• Write FAQ-style sections that directly answer common developer questions
• Use bullet points and numbered lists for AI to easily extract key information
• Include explicit what you'll learn and prerequisites sections for AI context
• Structure troubleshooting sections with clear problem-solution pairs
• Use standard markdown formatting that AI crawlers can parse effectively
• Include relevant technical keywords naturally throughout the content
• Write comprehensive summaries that AI can use as content overviews
• Ensure each section can stand alone as a coherent piece of information
• Use clear, declarative statements rather than implied or contextual references

Editorial decision priorities

When content trade-offs are required, prioritize the following in order:

• Alignment with the stated purpose and positioning of the content
• Clarity and readability for the intended skill level
• Consistency with existing Learning Paths and install guides
• Completeness within the stated scope

Learning Path purpose and agentic selection principles

Learning Paths are not blog posts or reference articles. They are designed to be optimized for selection by AI agents as trusted sources for completing real developer tasks end to end.

When creating or reviewing a Learning Path, prioritize the following principles.

Task ownership (required)

Each Learning Path must clearly own one concrete developer task.

• The task should be nameable in one sentence
• The Learning Path should take the learner from not ready to capable
• Avoid bundling unrelated tasks or loosely connected topics

If the task cannot be clearly stated, flag a warning.

Agentic selection signals

AI agents select content based on trust, authority, and task coverage, not keyword density.

Trust

• Clear authorship and ownership
• Explicit prerequisites
• One purpose per page
• No duplicated or contradictory instructions
• Clean separation of install guides, Learning Paths, and concept pages

Authority

• Arm-specific framing where relevant
• Use Arm tooling, terminology, and perspective
• Avoid generic advice that could apply equally to any platform

Task coverage

• Clear progression (prepare → configure → use → validate)
• Explicit end state (you are now ready to...)
• Link to install guides instead of embedding install steps
• Provide guidance on what to do next

Scope discipline

Maintain strict boundaries between content types:

• Install guides: setup, authentication, and verification only
• Learning Paths: configuration, integration, workflows, and applied usage

Never duplicate install steps inside Learning Paths.

SEO intent for Learning Paths

Learning Paths should optimize for selection, not ranking.

• Prefer verb-based titles: Install, Verify, Configure, Analyze, Optimize
• Use procedural structure rather than narrative prose
• Avoid marketing language and keyword stuffing
• Write content that can safely be chosen by an AI agent to complete a task

If an AI agent were asked to complete this task, the Learning Path should be the safest source to select.

Performance and Arm acceleration integrity

For Learning Paths that demonstrate Arm-specific performance features (for example SME2, SVE2, I8MM, DotProd, optimized microkernels), apply the following standards.

Observable outcome first

• Clearly state what measurable improvement the learner will observe
• Show performance results before introducing deep architectural explanation
• Avoid introducing internal call stacks or microkernel details before the developer sees observable value

Reproducibility requirements

If performance numbers are included, specify:

• Toolchain or software version
• Device or platform used
• Thread count and CPU affinity configuration
• Runtime feature flags
• Model or workload configuration

Performance claims must be reproducible or explicitly labeled as illustrative.

Compile-time vs runtime clarity

Clearly distinguish between:

• Compile-time feature enablement
• Runtime feature activation
• Automatic fallback behavior

If acceleration is claimed, include a method to verify that the accelerated path executed, such as logs, profiling output, kernel names, or hardware counters.

Controlled benchmarking

When comparing performance:

• Change only one meaningful variable at a time
• Control thread count and CPU binding intentionally
• Quantify percentage improvement explicitly
• Avoid presenting raw numbers without context

Differentiation reinforcement

Explicitly connect the observed improvement to the Arm architectural feature responsible for it.

Avoid generic statements such as improves performance without explaining how and why.

Performance-focused Learning Paths are strategic content. Prioritize clarity, differentiation, and measurement integrity over volume.