Finished PcVue assessment.

docs/resume/pcvue.md

@@ -0,0 +1,129 @@
+---
+title: PcVue assessment
+description: An assessment of the documentation provided by PCvue.
+hide:
+     # - toc
+     - navigation
+     - search
+---
+
+<style>
+ img {
+     border: 0.5px solid #ededed;
+     border-radius: 5px;
+ }
+</style>
+
+> ### Brief<br>
+> **October 2025**<br>
+> Briefly assess the quality of the [product documentation](https://www.pcvue.com/ProductHelp/PcVue/en/Content/AboutHelp/Welcome_PubWeb.php) of PcVue.
+
+![An image of the landing page of documentation section of PcVue](/src/pcvue-documentation-2728x1756.png){ height=300px }
+
+## Content clarity
+
+**Acronyms and technical jargon**: The documentation generally assumes familiarity with acronyms like HMI and SCADA. It would benefit from brief explanations in these areas. For example, this is from the first paragraph of an [overview page](https://www.pcvue.com/ProductHelp/PcVue/en/Content/HMI/Overview.php):
+
+---
+_The HMI (1) for your project is composed of mimics. Mimics (2) are easily and quickly developed to form menus, overviews, process diagrams, trend viewers and so on..._
+{ .annotate }
+
+1.  Even if the acronym has been written out elsewhere it needs to be re-introduced on every new page.
+2.  Mimics are a new concept as well, and the way this is written assumes the reader already knows what they are.
+---
+
+**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.
+
+**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.
+
+---
+
+## User experience
+
+**User experience**: Any documentation set that needs meta-documentation - like the [About this documentation](https://www.pcvue.com/ProductHelp/PcVue/en/Content/AboutHelp/HowToSearch_PubWeb.php) section - is signalling that it is not intuitive enough to use. A reader should not have to know about logical operators to use search functionality and interpret icons to understand their meaning. Good intuitive documentation sets don't need meta-documentation to understand how to use the documentation.
+
+**Search functionality**: The search feature needs enhancement to accommodate natural language queries rather than expecting users to know logical operators or regular expressions. Every reader's expectation is a search experience as good as Google; especially as the main way to navigate a large documentation set is through the search box.
+
+<figure>
+     <img src='/src/what-is-hmi.gif' alt='A simple search to find what HMI means'>
+     <figcaption>The search function is slow, fragmented, and can't handle questions</figcaption>
+</figure>
+
+**Getting Started section**: Preferably you need a Getting Started or QuickStart section. The installation minutiae gets in the way of someone who just wants the golden path. Notably, the main installation instructions are listed as the sixth item in the menu under the installation section.
+
+---
+
+## Information architecture
+
+**Linking examples with theory**: Examples should be integrated with related theoretical content instead of being isolated, like in the Application Architect section, where the [Examples](https://www.pcvue.com/ProductHelp/PcVue/en/Content/AA/Example_keyword.php) section is separate. This approach reinforces learning through immediate application.
+
+**Content types**: The content needs to be divided into content types more clearly: theory content, tutorial content, and reference content. There is an inconsistency in how the sections are organized. For example, the Application Architect section has a glossary, but the others do not. The [Diátaxis](https://diataxis.fr/) for technical writing explains content types and where they are applicable in more depth.
+
+**Headings and page structure**: Headings are an indicator of page structure for search engines and for AI answer engines. Headings like "Example 1", "The secondary navigation tree pop-up menu", "For the LAN Manager", and similar mean nothing in isolation - which is how engines parse a website.
+
+**Interlinking**: The content is light on internal links. There are **See more** boxes, but the linking between pages is relatively absent for dopcumentation describing one product. Internal linking helps readers make sens of the product as a whole and are critical for Search Engine Optimization (SEO).
+
+---
+
+## Design and technical
+
+**Page load times**: PHP, the language that MadCap Flare outputs content to, is slow and the documentation site has a noticeable lag when navigating pages and using search. A server-side language is good for dynamic content, but hamstrings static content - which is mainly how documentation is presented.
+
+**Print layout**: The print layout when using the print button is not well-styled for PDFs or physical printing. The text is too small, the spacing and styling is a facsimile of the web view when it should be simplified for the print view. Some compliance functions need good PDF functionality to prove that content was made available at a certain time for auditing purposes.
+
+
+<div class="grid cards" markdown>
+
+-   __PcVue print layout__
+
+    ---
+
+    ![The PcVue print layout](/src/pcvue-print-layout-1573x1433.png)
+
+-   __Styled print layout__
+
+    ---
+
+    ![A styled print layout](/src/spread-print-layout-1596x1872.png)
+
+</div>
+
+**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.
+
+**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.
+
+**Admonition overuse**: Excessive use of admonitions can diminish their impact. There are multiple pages with more than five admonitions per page. If everything is important, nothing is important. It’s essential to limit their frequency to maintain emphasis.
+
+---
+
+## General
+
+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 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.
+
+As a reader I get the sense the chapters have been written by different people and the documentation set does not work together.
+
+**My general recommendation would be an overhaul, starting with the information architecture, a technical infrastructure review, and then a general language and style standards review.**
+
+---
+
+<a href="https://gugulet.hu/resume" target="_blank" ><div class="button">See my résume</div></a>
+<div class='meta-icons'>
+          <a href='https://linkedin.com/in/gugulet-hu' target='_blank' >
+               <div>
+                    <span class='twemoji'><svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M19 3a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2zm-.5 15.5v-5.3a3.26 3.26 0 0 0-3.26-3.26c-.85 0-1.84.52-2.32 1.3v-1.11h-2.79v8.37h2.79v-4.93c0-.77.62-1.4 1.39-1.4a1.4 1.4 0 0 1 1.4 1.4v4.93zM6.88 8.56a1.68 1.68 0 0 0 1.68-1.68c0-.93-.75-1.69-1.68-1.69a1.69 1.69 0 0 0-1.69 1.69c0 .93.76 1.68 1.69 1.68m1.39 9.94v-8.37H5.5v8.37z'></path></svg></span> linkedin/gugulet-hu
+               </div>
+          </a>
+          <a href='https://gugulet.hu/technical/dev/explore/repos' target='_blank' >
+               <div>
+                    <span class='twemoji'><svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><path d='M2.6 10.59 8.38 4.8l1.69 1.7c-.24.85.15 1.78.93 2.23v5.54c-.6.34-1 .99-1 1.73a2 2 0 0 0 2 2 2 2 0 0 0 2-2c0-.74-.4-1.39-1-1.73V9.41l2.07 2.09c-.07.15-.07.32-.07.5a2 2 0 0 0 2 2 2 2 0 0 0 2-2 2 2 0 0 0-2-2c-.18 0-.35 0-.5.07L13.93 7.5a1.98 1.98 0 0 0-1.15-2.34c-.43-.16-.88-.2-1.28-.09L9.8 3.38l.79-.78c.78-.79 2.04-.79 2.82 0l7.99 7.99c.79.78.79 2.04 0 2.82l-7.99 7.99c-.78.79-2.04.79-2.82 0L2.6 13.41c-.79-.78-.79-2.04 0-2.82'></path></svg></span> gugulet.hu/dev
+               </div>
+          </a>
+     </div>

docs/src/stylesheets/_colours.css

@@ -8,6 +8,7 @@
      --secondary-colour: #EFE5DC;
      --tertiary-colour: #818589;
      --quarternary-colour: #FAF9F6;
+     --transparent: transparent;
 }
 
 /* Adjust Mkdocs colours */

docs/src/stylesheets/_fonts.css

@@ -167,7 +167,7 @@
 /* Typeset */
 
 .md-typeset {
-     p {
+     p, li, ul {
           font-family: var(--primary-font);
      }
 
@@ -179,7 +179,7 @@
      h1,
      h2,
      h3 {
-          font-family: var(--primary-font);
+          font-family: var(--secondary-font);
      }
 
      h4,

docs/src/stylesheets/_size.css

@@ -47,15 +47,15 @@
      }
 
      h2 {
-          font-size: max(calc(var(--text-variable-size) * 6), calc(var(--text-min-size) + 5px));
+          font-size: max(calc(var(--text-variable-size) * 4), calc(var(--text-min-size) + 5px));
      }
 
      h3 {
-          font-size: max(calc(var(--text-variable-size) * 4), calc(var(--text-min-size) + 4px));
+          font-size: max(calc(var(--text-variable-size) * 3.5), calc(var(--text-min-size) + 4px));
      }
 
      h4 {
-          font-size: max(calc(var(--text-variable-size) * 3), calc(var(--text-min-size) + 3px));
+          font-size: max(calc(var(--text-variable-size) * 2.8), calc(var(--text-min-size) + 3px));
      }
 
      h5 {

docs/src/stylesheets/g.css

@@ -21,6 +21,14 @@ body {
      width: 100%;
 }
 
+nav, .md-header {
+     background-color: var(--transparent);
+}
+
+a.md-header__button {
+     display: none !important;
+}
+
 .md-typeset a:hover {
      text-decoration: none;
 }

mkdocs.yml

@@ -81,7 +81,9 @@ nav:
   #         - Transactions: qself/transactions.md
   #         - Reference: qself/reference/index.md
   #         - Devices: qself/devices.md
-  - Resumé: resume.md
+  - Resumé: 
+    - resume.md
+    - PCVue assessment: resume/pcvue.md
 
 plugins:
   # Plugin to enable the blog feature. [https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin]
@@ -109,7 +111,7 @@ plugins:
       htmlmin_opts:
         remove_comments: true
       cache_safe: true
-  - search
+  # - search
   # Plugin to create index pages for each section. [https://github.com/oprypin/mkdocs-section-index]
   - section-index
   - tags
@@ -139,7 +141,7 @@ theme:
     - navigation.expand # Expand the navigation by default.
     - navigation.path # Add breadcrumbs to the top of the article.
     - navigation.prune # Only the visible pages are in the menu.
-    - navigation.tabs # Tabs at the top for the chapters (i.e Platform Admin, Platform Tools, ...).
+    - navigation.tabs: false # Tabs at the top for the chapters (i.e Platform Admin, Platform Tools, ...).
     - navigation.tracking # Address bar updated with active anchor.
     - navigation.top # Back to the top button on every page.
     - navigation.footer # Previous and next buttons in the footer.