Este artículo ha sido aportado por Dmitri Popov, redactor técnico del equipo de documentación de SUSE. 

Empecemos por decir lo obvio. Los textos bien escritos tienen tres propiedades básicas:

• ortografía y puntuación correctas
• gramática correcta
• consistencia

Se requiere corrección

Si bien un corrector ortográfico puede encargarse del primer elemento de la lista, puede detectar los problemas gramaticales más comunes con LanguageTool .

Sin embargo, la parte de la consistencia es complicada. ¿ Barra de estado o barra de estado ? ¿ EXT3  o Ext3 ? ¿ Web o red ? página de manual  o página de manual ?

La consistencia es clave

A veces solo hay una opción correcta. A veces, ambas grafías son correctas, por lo que debe tomar una decisión consciente para elegir una. La consistencia es la razón de ser  de una guía de estilo, un compendio codificado de reglas y prácticas que deben seguirse para mantener el uso del lenguaje, bueno, consistente. Para los escritores, y los escritores técnicos en particular, tener una guía de estilo es imprescindible. Pero consultarlo cada vez que tengas dudas puede convertirse rápidamente en una molestia. Y si está interesado en contribuir a la documentación, sin ser un escritor técnico, lo más probable es que leer la guía de estilo sea lo último que quiera hacer.

Vale agrega valor

Aquí es donde Vale  entra en escena. Vale es un filtro de gramática, estilo y uso del lenguaje para el idioma inglés. En programación, linter es una herramienta que analiza el código fuente para detectar y señalar errores, bugs, errores de estilo, etc. en tiempo real. Eso es lo que hace Vale también, pero en lugar de código funciona con el idioma inglés. En pocas palabras, Vale analiza el texto comparándolo con el conjunto de reglas de estilo suministrado, detecta problemas y sugiere soluciones mientras escribe .

Una guía de estilo es la premisa

Para que Vale haga su trabajo, debe proporcionarle una guía de estilo. Hay varias guías de estilo compatibles con Vale entre las que puede elegir, incluida la Guía de estilo de escritura de Microsoft , la Guía de estilo de documentación para desarrolladores de Google y otras. Pero como está leyendo esto, es muy probable que esté interesado en SUSE o que trabaje con productos y soluciones de SUSE, por lo que la Guía de estilo de documentación de SUSE   es la referencia que le gustaría usar con Vale. ¿Pero cómo? Me alegra que hayas preguntado.

El proyecto te espera

Durante Hack Week 21, creé una versión compatible con Vale de la Guía de estilo de documentación de SUSE . Todo lo que tiene que hacer es instalar Vale, agregarle la guía y  conectar Vale a su editor preferido . El archivo README proporciona instrucciones sobre cómo lograrlo. Si quieres contribuir, has encontrado un error o tienes una sugerencia de mejora, abre un problema en la sección Problemas .