Windsurf

Configura Windsurf como tu assistant de redacción

Transforma Windsurf en un experto en documentación que entienda tu guía de estilo, tus componentes y el contexto de tu proyecto mediante reglas del espacio de trabajo y memorias.

​

Uso de Windsurf con Mintlify

El assistant Cascade de Windsurf puede configurarse para redactar documentación según tus estándares utilizando componentes de Mintlify. Las reglas del espacio de trabajo y las memorias proporcionan contexto persistente sobre tu proyecto, lo que garantiza sugerencias más coherentes de parte de Cascade.

• Reglas del espacio de trabajo se almacenan en tu repositorio de documentación y se comparten con tu equipo.
• Memorias proporcionan contexto individual que se acumula con el tiempo.

Recomendamos configurar reglas del espacio de trabajo para unificar los estándares de documentación compartidos. Puedes desarrollar memorias conforme trabajas, pero como no se comparten, no serán coherentes entre los miembros del equipo.

Crea reglas del espacio de trabajo en el directorio .windsurf/rules de tu repositorio de documentación. Consulta Memories & Rules en la documentación de Windsurf para obtener más información.

​

Regla de ejemplo para el espacio de trabajo

Esta regla proporciona a Cascade contexto sobre los componentes de Mintlify y las mejores prácticas generales de redacción técnica.

Puedes usar esta regla de ejemplo tal cual o personalizarla para tu documentación:

• Estándares de redacción: Actualiza las pautas de lenguaje para alinearlas con tu guía de estilo.
• Patrones de componentes: Agrega componentes específicos del proyecto o modifica los ejemplos existentes.
• Ejemplos de código: Reemplaza los ejemplos genéricos con llamadas y respuestas reales de la API para tu producto.
• Preferencias de estilo y tono: Ajusta la terminología, el formato y otras reglas.

Guarda tu regla como un archivo .md en el directorio .windsurf/rules de tu repositorio de documentación.

# Regla de redacción técnica de Mintlify

## Contexto del proyecto

- Este es un proyecto de documentación en la plataforma Mintlify
- Usamos archivos MDX con frontmatter YAML  
- La navegación se configura en `docs.json`
- Seguimos las mejores prácticas de redacción técnica

## Estándares de redacción

- Usa segunda persona ("tú") para las instrucciones
- Escribe en voz activa y tiempo presente
- Comienza los procedimientos con prerrequisitos
- Incluye resultados esperados para los pasos principales
- Usa encabezados descriptivos y ricos en palabras clave
- Mantén las oraciones concisas pero informativas

## Estructura de página requerida

Cada página debe comenzar con frontmatter:

```yaml
---
title: "Título claro y específico"
description: "Descripción concisa para SEO y navegación"
---
```

## Componentes de Mintlify

### docs.json

- Consulta el [esquema de docs.json](https://mintlify.com/docs.json) al construir el archivo docs.json y la navegación del sitio

### Llamadas de atención

- `<Note>` para información suplementaria útil
- `<Warning>` para precauciones importantes y cambios disruptivos
- `<Tip>` para mejores prácticas y consejos de expertos  
- `<Info>` para información contextual neutral
- `<Check>` para confirmaciones de éxito

### Ejemplos de código

- Cuando sea apropiado, incluye ejemplos completos y ejecutables
- Usa `<CodeGroup>` para ejemplos en múltiples lenguajes
- Especifica etiquetas de lenguaje en todos los bloques de código
- Incluye datos realistas, no marcadores de posición
- Usa `<RequestExample>` y `<ResponseExample>` para documentación de API

### Procedimientos

- Usa el componente `<Steps>` para instrucciones secuenciales
- Incluye pasos de verificación con componentes `<Check>` cuando sea relevante
- Divide procedimientos complejos en pasos más pequeños

### Organización de contenido

- Usa `<Tabs>` para contenido específico de plataforma
- Usa `<Accordion>` para divulgación progresiva
- Usa `<Card>` y `<CardGroup>` para destacar contenido
- Envuelve imágenes en componentes `<Frame>` con texto alternativo descriptivo

## Requisitos de documentación de API

- Documenta todos los parámetros con `<ParamField>` 
- Muestra la estructura de respuesta con `<ResponseField>`
- Incluye ejemplos tanto de éxito como de error
- Usa `<Expandable>` para propiedades de objetos anidados
- Siempre incluye ejemplos de autenticación

## Estándares de calidad

- Prueba todos los ejemplos de código antes de publicar
- Usa rutas relativas para enlaces internos
- Incluye texto alternativo para todas las imágenes
- Asegura una jerarquía de encabezados adecuada (comienza con h2)
- Verifica patrones existentes para mantener consistencia

​

Trabajar con Cascade

Una vez que hayas configurado tus reglas, puedes usar Cascade para ayudarte con varias tareas de documentación. Consulta Cascade en la documentación de Windsurf para obtener más información.

​

Ejemplos de indicaciones

Redacción de contenido nuevo:

Crea una nueva página que explique cómo autenticarse con nuestra API. Incluye ejemplos de código en JavaScript, Python y cURL.

Mejorar el contenido existente:

Revisa esta página y sugiere mejoras para mayor claridad y uso de componentes. Concéntrate en hacer que los pasos sean más fáciles de seguir.

Crear ejemplos de código:

Genera un ejemplo de código completo que muestre el manejo de errores para este endpoint de API. Utiliza datos realistas e incluye las respuestas esperadas.

Mantener la consistencia:

Verifica si esta nueva página cumple con nuestros estándares de documentación y sugiere los cambios necesarios.