Last week, I did separate walk-throughs with two writers. My intention was to gain insight into the issues a typical user might encounter, and to use that information to improve the “getting started” repo I had created. I helped them install, configure, and start using Vale on their systems.
Installing Vale by using brew was problematic, so we installed the precompiled Vale binary instead. We also copied the .vale.ini configuration file and /styles directory to their doc project and updated the configuration to work with .adoc files.
However, when we ran Vale against one of their .adoc content files, we got a mysterious error. Searching online didn’t help us solve the issue right away. I made a mental note to try to reproduce the error later. The writer had been preparing a presentation on Vale for his documentation project team, but given these setbacks they decided to delay that presentation.
The second writer completed the installation process on their own. Our meeting was more of a conversation than a walkthrough. It seemed like they were ready for a style that was more Red Hat-specific than the generic ones I provided.
This weekend, I put my insights from those two walkthroughs to work by completely updating the getting started repo, https://github.com/rolfedh/studious-fortnight:
- Removing the previous
/stylesfolder and.vale.inifile. - Adding the
.valestyles folder and.vale.inithat Fabrice and Yana developed for the Che eclipse documentation project. - Updating and expanding
README.mdwith new information to help you get started with using Vale. - Adding a “Troubleshooting common errors” topic to help newcomers identify and correct common issues.
- Added a “Vale at Red Hat Blog” blog to the repo.
That blog will cover information similar to project and release notes. In contrast, these “vale notes” posts will focus more on my personal insights.
Rolfe Dlugy-Hegwer 