Introduction
Imagine this scenario: John writes an API documentation that feels haphazard and inconsistent, with almost every word in bold, italics, or both, making it difficult to read and navigate. To make matters worse, his friend Mary collaborates and makes the situation even more chaotic. She underlines almost every single word. 🤦♂️
What's the solution? John's documentation needs linting and formatting to restore consistency and make it easier for readers to understand.
How can we do this? One way to improve John's documentation is by using a standardized style guide and a tool that can help identify and fix this inconsistent formatting.
Introducing Vale
Vale is a versatile linting tool that goes beyond basic syntax checks. It examines your code documentation, identifying potential problems with style, clarity, and even accuracy. Think of it as a grammar checker, but specifically for your documentation.
Vale supports and gets utilized by big companies such as Google, Microsoft, GitHub, and RedHat. It has a variety of packages ready for implementation. It provides flexibility, allowing developers to create their own style guides from the ground up or use its config generator.
You can use this generator to create configuration files for your style guide, leveraging existing base and supplementary style implementations.
Why use Vale for your documentation?
Applying a linter to your documentation ensures adherence to your style guides. Notable benefits include:
Detecting errors and stylistic issues in your technical documentation.
Establishing coherence across different sections of your documentation.
Ensuring consistency when team members document your API, framework, or app.
Eliminating the need for manual verification of code blocks and written content against your style guide.
Enhancing the reading experience for developers and the audience.
This brings us to the next section: Installing Vale
Getting Started with Vale
Installation is pretty simple. Open Terminal on Linux and run sudo snap install vale, on Windows, run choco install vale.
Inside Visual Studio Code, Go to Extensions and install Vale Visual Studio Code Extension
After the installation, clone this GitHub Repository; It contains a boilerplate for getting started.
Inside the vale-boilerplate directory, create a file named hello.md. Copy and paste the following text into hello.md.
## Demo
- This boy is a technical writer. He is very very good. And however, He does a good job actually.
- He writes technical documents that explains complex informations in a clear and concise manner.
- attention to detail, and the ability to communicate complex informations in a simple way.
- They often work closely with engineers, developers, and other technical professionals to create accurate and informative contents.
- If you are interested in technology and enjoy writing, a career as a technical writer may be a good fit for you.
Now Vale will check the content against your style guide and highlight any issues.
From this point, you can now go ahead and fix these inconsistencies. The result will be a more polished and clear code document.
You can verify this by running vale followed by filename, in this case vale hello.md, will get the job done.
Voila, no errors. Feel free to take vale to the next level by using custom styles
More Resources
Getting Started with Vale using Vale with GitHub actions and the Terminal
Using Vale in Visual Studio Code
Using Vale with Third Party Style Guides and Custom Rules
Vale - Official Documentation Website
Conclusion
To wrap it up, utilizing Vale for your documentation can significantly enhance the clarity, consistency, and quality of your content.
By adhering to standardized style guides and leveraging the powerful features of Vale, you can ensure that your documentation remains professional and easy to understand, benefiting both your team and your audience. Happy documenting!