From bdf5b999ddfd40b66d8ecdff0bab2cf3a3374e51 Mon Sep 17 00:00:00 2001 From: g* Date: Mon, 27 Oct 2025 13:09:53 +0100 Subject: [PATCH] Fixing typos. --- docs/resume/pcvue.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/resume/pcvue.md b/docs/resume/pcvue.md index 1665b0a..270f3cb 100644 --- a/docs/resume/pcvue.md +++ b/docs/resume/pcvue.md @@ -34,7 +34,7 @@ _The HMI (1) for your project is composed of mimics. Mimics (2) are easily and q **Assumed knowledge**: Many pages presuppose a significant amount of technical knowledge, which could confuse readers - especially those new to the industry. The first principle of technical writing is that every page is page one and the reader should find all the context they need on the page (or linked on the page). -This is especially jarring on the landing page of the Product Documentation: PcVue has the description HMI/SCADA, FrontVue has the description Light HMI, and EmVue has the description Energy Monitoring. Of those, only EmVue is understandable to a new user. Using full blurbs that decsribe what the documentation set contains would be better for understanding. +This is especially jarring on the landing page of the Product Documentation: PcVue has the description HMI/SCADA, FrontVue has the description Light HMI, and EmVue has the description Energy Monitoring. Of those, only EmVue is understandable to a new user. Using full blurbs that describe what the documentation set contains would be better for understanding. **Use-cases**: The absence of real-world use cases leaves a gap in understanding how the software works in practice. There are marketing use-cases on the main website, but they would do more to give product documentation clarity. @@ -92,7 +92,7 @@ This is especially jarring on the landing page of the Product Documentation: PcV **Lists and tables**: When to use a table, a list, or another element should be clearer. There were instances were a table would have been better than a list and vise-versa. The formatting of both needs attention: lists are too spaced out and tables contain multiple header rows in the same table. -**Diagrams and images**: Diagrams are a great tool for getting information across visually, particularly to illustrate complex processes and concepts. There are no diagrams in the documentation. Tools like Mermaid allow you to create diagrams dynamically, without using image editing application. The general quality of the screenshots and images is low, and there are no captions. Captions are important for SEO and for accesibility for visually impaired readers. Having images under **Show pictures** dropdowns is a suboptimal user experince. It's an additional click for little gain. +**Diagrams and images**: Diagrams are a great tool for getting information across visually, particularly to illustrate complex processes and concepts. There are no diagrams in the documentation. Tools like Mermaid allow you to create diagrams dynamically, without using image editing application. The general quality of the screenshots and images is low, and there are no captions. Captions are important for SEO and for accessibility for visually impaired readers. Having images under **Show pictures** dropdowns is a suboptimal user experience. It's an additional click for lß ittle gain. **Font and presentation layer**: The font on the main site is more legible and overall styling is more visually appealing compared to the documentation site. Presentation matters, even for highly technical audiences. @@ -104,7 +104,7 @@ This is especially jarring on the landing page of the Product Documentation: PcV The documentation is arranged around how the company views the software and not how users use it. A compliance and audit professional would benefit from a user flow designed for their needs and understanding, same for an integration or process engineer. -The documentation is written like a book, with the expectation that readers will read from top to botttom. This is not how people read documentation. Documentation is primarily diven by search and read in snippets. Readers come with questions and expect answers with full context in a nutshell. +The documentation is written like a book, with the expectation that readers will read from top to bottom. This is not how people read documentation. Documentation is primarily driven by search and read in snippets. Readers come with questions and expect answers with full context in a nutshell. The language scores highly on the [Flesch-Kincaid Grade Level](https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests), indicating that it can be improved for clarity and flow. This would need a full review of the content to set standards that make it more readable and understandable.