Consejos para una buena búsqueda
Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →
DocSearch puede funcionar con casi cualquier sitio web, pero hemos observado que ciertas estructuras de sitio ofrecen resultados más relevantes o tiempos de indexación más rápidos. En esta página compartiremos consejos para aprovechar al máximo DocSearch.
Usa un sitemap.xml
Si incluyes un sitemap en tu configuración, DocSearch lo usará para navegar directamente a las páginas a indexar. Las páginas aún se rastrean, lo que significa que extraemos todos los enlaces válidos.
Recomendamos encarecidamente agregar un sitemap.xml a tu sitio web si aún no tienes uno. Esto acelerará la indexación y además te dará mayor control sobre qué páginas incluir o excluir del proceso.
Los sitemaps también se consideran buena práctica para otros aspectos, incluido el SEO (más información sobre sitemaps).
Estructura la jerarquía de información
DocSearch funciona mejor con documentación estructurada. La relevancia de los resultados se basa en la jerarquía estructural del contenido. En términos simples, significa que leemos los encabezados <h1>, ..., <h6> de tu página para inferir la jerarquía de información. Esta jerarquía aporta contexto a tus registros.
La documentación comienza explicando conceptos genéricos y luego profundiza en detalles específicos. Esto se representa en tu HTML mediante la jerarquía de encabezados. Por ejemplo, los conceptos bajo un <h4> son más específicos que los bajo un <h2> en la misma página. Cuanto antes aparezca la información en la página, mayor será su clasificación.
DocSearch usa esta estructura para ajustar la relevancia de los resultados y permitir posibles filtrados. Las documentaciones que siguen este patrón suelen tener mejor relevancia en sus resultados de búsqueda.
Determinar la profundidad adecuada de tu árbol de documentación y cómo dividir el contenido son dos de las tareas más complejas. Para páginas grandes, recomendamos 4 niveles (de lvl0 a lvl3). Como mínimo, sugerimos tres niveles distintos.
Nota: No es obligatorio usar etiquetas <hX>; puedes usar clases en su lugar (por ejemplo, <span class="title-X">). Deberás actualizar el valor de configuración selectors.
Asigna una clase única al contenedor de contenido
DocSearch extrae contenido basado en la estructura HTML. Recomendamos agregar una class personalizada al elemento HTML que envuelve todo tu contenido textual. Esto ayudará a precisar los selectores hacia el contenido relevante.
Este identificador único hará tu configuración más robusta al garantizar que el contenido indexado sea relevante. Es la forma más confiable de excluir contenido irrelevante en encabezados, barras laterales y pies de página.
Agrega anclas a los encabezados
Al usar encabezados (como se mencionó), también deberías agregar un ancla personalizada a cada uno. Los anclas se definen con atributos HTML (name o id) en los encabezados, permitiendo a los navegadores desplazarse directamente a esa posición. Se acceden mediante enlaces con # seguido del ancla.
DocSearch respetará estos anclas y llevará automáticamente a tus usuarios al ancla más cercano al resultado de búsqueda seleccionado.
Marcar la página activa en la navegación
Si usas una navegación multinivel, recomendamos marcar cada nivel activo con una clase CSS personalizada. Esto ayudará a DocSearch a entender dónde encaja la página actual en la jerarquía del sitio.
Por ejemplo, si tu página troubleshooting.html está bajo el menú "Instalación" en la barra lateral, recomendamos agregar una clase CSS personalizada a los enlaces de "Instalación" y "Solución de problemas".
El nombre de la clase CSS no importa, siempre que pueda usarse como parte de un selector CSS.
Consistencia de tu contenido
La coherencia es un pilar fundamental para una documentación significativa. Aumenta la inteligibilidad de un documento y reduce el tiempo necesario para que el usuario encuentre la información deseada. El tema del documento debe ser identificable y su estructura debe estar claramente delimitada.
La jerarquía debe mantener siempre la misma profundidad. Intenta evitar registros huérfanos como introducciones/conclusiones aisladas o apartados sueltos. Los selectores deben ser eficaces para cada documento y resaltar la jerarquía adecuada. Deben coincidir con los elementos deseados según su nivel. Ten cuidado de evitar el efecto borde capturando elementos superfluos inesperados.
Los selectores deben capturar información de páginas web con documentación real y permanecer inefectivos en otras (p.ej. páginas de inicio, índices, etc.). Recomendamos encarecidamente definir una clase dedicada para el contenedor DOM principal que incluya el contenido documental real, como .DocSearch-content.
Dado que la documentación debe ser interactiva, es crucial verbalizar conceptos con vocabulario estandarizado. Esta redundancia, potenciada por la experiencia de búsqueda (desplegable), permite incluso un aprendizaje durante la escritura. La forma de encontrar información juega un papel clave para guiar al usuario hacia el conocimiento recuperado. También puedes utilizar la función de sinónimos.
Evita duplicados promoviendo la unicidad
Cuanto más tiempo consuma leer la documentación, más tedioso y reacio será su uso. Debes evitar puntos confusos o documentos "cajón de sastre". Además de ser poco útiles, estos documentos pueden resultar confusos y contraproducentes.
Los duplicados introducen ruido y desorientan a los usuarios. Por eso siempre debes enfocarte en el contenido relevante y evitar duplicar información en tu sitio (como páginas de inicio que resumen todo, etc.). Si los duplicados son inevitables por pertenecer a múltiples conjuntos de datos (p.ej. diferentes versiones), debes usar facetas.
Concisión
Lo que está claramente pensado se expresa con claridad y concisión.
Te recomendamos encarecidamente leer este artículo sobre cómo construir una búsqueda útil para documentación técnica.