Skip to main content

UX Writing Tips for YAML Files

Last updated on
Open a doc issue   |   Edit this page

These guidelines help you create effective microcopy for YAML files. Focus on clarity, brevity, and user value to ensure better configuration and usability.

Adhering to these guidelines will help you create YAML files that are functional and user-friendly.

Field inputs

Clear field inputs make YAML configurations intuitive. Follow these best practices:

  • Use descriptive labels and concise descriptions for immediate clarity.
  • State requirements explicitly (e.g., "Required field. Use lowercase letters only").
  • Provide examples for complex inputs to minimize confusion.

Metadata descriptions

Metadata descriptions in catalog-info.yaml should communicate the purpose and context of a component clearly and succinctly. Follow these principles:

  1. Start with an active verb to emphasize action.
  2. State the component’s main purpose—what it does and who it serves.
  3. Include relevant context, such as relationships to other systems.
  4. Be concise—focus on what’s essential.

Writing guidelines

To craft clear, impactful descriptions, follow this three-step process:

1. Analyze

Answer key questions before you start:

  • What does the component do?
  • Who uses it, and why?
  • What value does it provide?

2. Draft

Structure your description with these elements:

  • Active verb: Highlight what the component does.
  • Primary purpose: Explain the function and value.
  • Audience or context: Specify who benefits or its system role.
metadata:
  description: [VERB] + [PRIMARY PURPOSE] + [FOR WHOM/WHAT] + [ESSENTIAL CONTEXT]

3. Polish

Ensure your descriptions are:

  • Concise: Keep it under three sentences.
  • User-focused: Highlight benefits over technical details.
  • Accessible: Avoid technical jargon; use plain language.
  • Consistent: Write in the present tense and include only relevant technology.

Examples with explanations

✅ Good examples

# Clear purpose, context, and audience
metadata:
  description: Processes customer payments for the e-commerce platform using Stripe integration.

# Highlights user and functionality
metadata:
  description: Enables marketing teams to schedule and publish social media content across multiple platforms.

# Specifies relationships to other systems
metadata:
  description: Aggregates inventory data from warehouse systems to provide real-time stock levels for the retail website.

Why they work:

  • Starts with active verbs like "Processes," "Enables," and "Aggregates."
  • Clearly defines the primary purpose and context.
  • Specifies who uses the component and how it integrates with other systems.
  • Stays concise, delivering only the necessary information.

❌ Poor examples

# Too vague
metadata:
  description: Handles data processing

# Overloaded with technical jargon
metadata:
  description: Implements NodeJS-based microservice using Redis cache and Kafka streams for event-driven architecture.

# Focused on implementation details, not purpose
metadata:
  description: Written in Python 3.9 with FastAPI framework and PostgreSQL database

# Too long and unfocused
metadata:
  description: A component that manages user authentication and authorization, handles session management, and provides security features like password hashing, JWT token generation, and OAuth2 integration with multiple providers such as Google, Facebook, and Twitter, including rate limiting capabilities

Why they don’t work:

  • The first example is too generic and lacks purpose.
  • The second example focuses on technical jargon without explaining its value.
  • The third example centers on implementation details rather than the component’s role.
  • The fourth example is overly verbose, making it hard to scan and understand.

Check your knowledge

YAML WRITING TIPS

Be Direct and Clear

Direct and clear language in YAML fields enhances user understanding, reducing confusion and errors.

By eliminating unnecessary words, YAML becomes more user-friendly and maintainable.

This approach allows users to grasp required information quickly, making field descriptions more straightforward and less ambiguous.

Be Direct and Clear
Which of the following is the most direct and clear YAML input for a component name?
YAML WRITING TIPS

Use Short, Specific Descriptions

Concise, specific descriptions in YAML fields balance brevity and informativeness.

This approach reduces cognitive load and improves scannability, enabling users to quickly find needed information without feeling overwhelmed.

The goal is to clearly communicate requirements while avoiding information overload and insufficient detail.

Use Short, Specific Descriptions
Which description is both short and specific for a 'system' field in catalog-info.yaml?
YAML WRITING TIPS

Avoid Generic Descriptions

Generic descriptions create ambiguity, making it hard for users to determine what information is required or how it will be used.

Specific descriptions, on the other hand, help users understand each field's purpose. This specificity is crucial for features like service discovery and dependency tracking.

Clear, precise descriptions promote consistency and clarity across entries, while generic terms leave users uncertain about a field's exact function.

Avoid Generic Descriptions
Which of these descriptions avoids being generic for a 'type' field in catalog-info.yaml?
YAML WRITING TIPS

Provide Context in Descriptions

Contextual descriptions in YAML fields help users understand the impact and use of their input within the Alchemy catalog.

This insight enables informed decision-making, resulting in more useful and consistent catalog entries.

By providing context, users can supply meaningful information that integrates seamlessly with the platform, enhancing overall catalog quality.

Provide Context in Descriptions
Which description provides the best context for a 'description' field?
YAML WRITING TIPS

Use Actionable Language in Fields

Action-oriented language in YAML fields guides users effectively.

Using verbs and clear instructions, it specifies exactly what actions to take. This approach is crucial in template files where user input impacts system behavior.

Explicit directions enhance the accuracy and completeness of catalog entries, simplifying the process and ensuring users provide precise, comprehensive information.

Use Actionable Language in Fields
Which field uses the most actionable language?
YAML WRITING TIPS

Be Concise and Relevant

Concise YAML fields focus on essential information, enhancing readability and maintainability.

By avoiding filler and jargon, they ensure only relevant details are captured, resulting in higher-quality catalog entries.

This approach makes YAML files cleaner, easier to manage, and more accessible to users of all expertise levels.

Be Concise and Relevant
Which of these is the most concise and relevant description for a 'purpose' field?