g_it/site
g_it/site
1
0
Fork 0
Code Issues Releases 1 Wiki Activity Actions
site/deploy/resume/pcvue/index.html

517 lines
No EOL
22 KiB
HTML
Executable file
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" class="no-js">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="description" content="An assessment of the documentation provided by PcVue.">
<meta name="author" content="Gugulethu Hlekwayo">
<link rel="canonical" href="https://gugulet.hu/resume/pcvue/">
<link rel="icon" href="../../assets/images/favicon.png">
<meta name="generator" content="zensical-0.0.20">
<title>PcVue assessment - Gugulethu Hlekwayo</title>
<link rel="stylesheet" href="../../assets/stylesheets/modern/main.d4922b3c.min.css">
<link rel="stylesheet" href="../../assets/stylesheets/modern/palette.dfe2e883.min.css">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Inter:300,300i,400,400i,500,500i,700,700i%7CJetBrains+Mono:400,400i,700,700i&display=fallback">
<style>:root{--md-text-font:"Inter";--md-code-font:"JetBrains Mono"}</style>
<link rel="stylesheet" href="../../assets/css/g.css">
<script>__md_scope=new URL("../..",location),__md_hash=e=>[...e].reduce(((e,t)=>(e<<5)-e+t.charCodeAt(0)),0),__md_get=(e,t=localStorage,a=__md_scope)=>JSON.parse(t.getItem(a.pathname+"."+e)),__md_set=(e,t,a=localStorage,_=__md_scope)=>{try{a.setItem(_.pathname+"."+e,JSON.stringify(t))}catch(e){}},document.documentElement.setAttribute("data-platform",navigator.platform)</script>
</head>
<body dir="ltr" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="indigo">
<input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
<input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
<a href="#brief" class="md-skip">
Skip to content
</a>
</div>
<div data-md-component="announce">
</div>
<header class="md-header md-header--shadow" data-md-component="header">
<nav class="md-header__inner md-grid" aria-label="Header">
<a href="../.." title="Gugulethu Hlekwayo" class="md-header__button md-logo" aria-label="Gugulethu Hlekwayo" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-book-open" viewBox="0 0 24 24"><path d="M12 7v14M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
</a>
<label class="md-header__button md-icon" for="__drawer">
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-menu" viewBox="0 0 24 24"><path d="M4 5h16M4 12h16M4 19h16"/></svg>
</label>
<div class="md-header__title" data-md-component="header-title">
<div class="md-header__ellipsis">
<div class="md-header__topic">
<span class="md-ellipsis">
Gugulethu Hlekwayo
</span>
</div>
<div class="md-header__topic" data-md-component="header-topic">
<span class="md-ellipsis">
PcVue assessment
</span>
</div>
</div>
</div>
<form class="md-header__option" data-md-component="palette">
<input class="md-option" data-md-color-media="none" data-md-color-scheme="default" data-md-color-primary="custom" data-md-color-accent="indigo" aria-hidden="true" type="radio" name="__palette" id="__palette_0">
</form>
<script>var palette=__md_get("__palette");if(palette&&palette.color){if("(prefers-color-scheme)"===palette.color.media){var media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']");palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent")}for(var[key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
<label class="md-header__button md-icon" for="__search">
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-search" viewBox="0 0 24 24"><path d="m21 21-4.34-4.34"/><circle cx="11" cy="11" r="8"/></svg>
</label>
<div class="md-search" data-md-component="search" role="dialog" aria-label="Search">
<button type="button" class="md-search__button">
Search
</button>
</div>
<div class="md-header__source">
</div>
</nav>
</header>
<div class="md-container" data-md-component="container">
<main class="md-main" data-md-component="main">
<div class="md-main__inner md-grid">
<div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" hidden>
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
<label class="md-nav__title" for="__drawer">
<a href="../.." title="Gugulethu Hlekwayo" class="md-nav__button md-logo" aria-label="Gugulethu Hlekwayo" data-md-component="logo">
<svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-book-open" viewBox="0 0 24 24"><path d="M12 7v14M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z"/></svg>
</a>
Gugulethu Hlekwayo
</label>
<ul class="md-nav__list" data-md-scrollfix>
<li class="md-nav__item">
<a href="../.." class="md-nav__link">
<span class="md-ellipsis">
Homepage
</span>
</a>
</li>
<li class="md-nav__item">
<a href="../" class="md-nav__link">
<span class="md-ellipsis">
Resume
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
<div class="md-sidebar__scrollwrap">
<div class="md-sidebar__inner">
<nav class="md-nav md-nav--secondary" aria-label="On this page">
<label class="md-nav__title" for="__toc">
<span class="md-nav__icon md-icon"></span>
On this page
</label>
<ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
<li class="md-nav__item">
<a href="#brief" class="md-nav__link">
<span class="md-ellipsis">
Brief
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#content-clarity" class="md-nav__link">
<span class="md-ellipsis">
Content clarity
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#user-experience" class="md-nav__link">
<span class="md-ellipsis">
User experience
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#information-architecture" class="md-nav__link">
<span class="md-ellipsis">
Information architecture
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#design-and-technical" class="md-nav__link">
<span class="md-ellipsis">
Design and technical
</span>
</a>
</li>
<li class="md-nav__item">
<a href="#general" class="md-nav__link">
<span class="md-ellipsis">
General
</span>
</a>
</li>
</ul>
</nav>
</div>
</div>
</div>
<div class="md-content" data-md-component="content">
<article class="md-content__inner md-typeset">
<h1>PcVue assessment</h1>
<style>
img {
border: 0.5px solid #ededed;
border-radius: 5px;
}
</style>
<blockquote>
<h3 id="brief">Brief<br><a class="headerlink" href="#brief" title="Permanent link">&para;</a></h3>
<p><strong>October 2025</strong><br>
Briefly assess the quality of the <a href="https://www.pcvue.com/ProductHelp/PcVue/en/Content/AboutHelp/Welcome_PubWeb.php">product documentation</a> of PcVue.</p>
</blockquote>
<p><img alt="An image of the landing page of documentation section of PcVue" height="300px" src="..//src/pcvue-documentation-2728x1756.png" /></p>
<h2 id="content-clarity">Content clarity<a class="headerlink" href="#content-clarity" title="Permanent link">&para;</a></h2>
<p><strong>Acronyms and technical jargon</strong>: 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 <a href="https://www.pcvue.com/ProductHelp/PcVue/en/Content/HMI/Overview.php">overview page</a>:</p>
<hr />
<p class="annotate"><em>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...</em></p>
<ol>
<li>Even if the acronym has been written out elsewhere it needs to be re-introduced on every new page.</li>
<li>Mimics are a new concept as well, and the way this is written assumes the reader already knows what they are.</li>
</ol>
<hr />
<p><strong>Assumed knowledge</strong>: 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).</p>
<p>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.</p>
<p><strong>Use-cases</strong>: 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.</p>
<hr />
<h2 id="user-experience">User experience<a class="headerlink" href="#user-experience" title="Permanent link">&para;</a></h2>
<p><strong>User experience</strong>: Any documentation set that needs meta-documentation - like the <a href="https://www.pcvue.com/ProductHelp/PcVue/en/Content/AboutHelp/HowToSearch_PubWeb.php">About this documentation</a> 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.</p>
<p><strong>Search functionality</strong>: 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.</p>
<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>
<p><strong>Getting Started section</strong>: 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.</p>
<hr />
<h2 id="information-architecture">Information architecture<a class="headerlink" href="#information-architecture" title="Permanent link">&para;</a></h2>
<p><strong>Linking examples with theory</strong>: Examples should be integrated with related theoretical content instead of being isolated, like in the Application Architect section, where the <a href="https://www.pcvue.com/ProductHelp/PcVue/en/Content/AA/Example_keyword.php">Examples</a> section is separate. This approach reinforces learning through immediate application.</p>
<p><strong>Content types</strong>: 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 <a href="https://diataxis.fr/">Diátaxis</a> for technical writing explains content types and where they are applicable in more depth.</p>
<p><strong>Headings and page structure</strong>: 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.</p>
<p><strong>Interlinking</strong>: The content is light on internal links. There are <strong>See more</strong> boxes, but the linking between pages is relatively absent for documentation describing one product. Internal linking helps readers make sense of the product as a whole and are critical for Search Engine Optimization (SEO).</p>
<hr />
<h2 id="design-and-technical">Design and technical<a class="headerlink" href="#design-and-technical" title="Permanent link">&para;</a></h2>
<p><strong>Page load times</strong>: 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.</p>
<p><strong>Print layout</strong>: 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.</p>
<div class="grid cards">
<ul>
<li>
<p><strong>PcVue print layout</strong></p>
<hr />
<p><img alt="The PcVue print layout" src="..//src/pcvue-print-layout-1573x1433.png" /></p>
</li>
<li>
<p><strong>Styled print layout</strong></p>
<hr />
<p><img alt="A styled print layout" src="..//src/spread-print-layout-1596x1872.png" /></p>
</li>
</ul>
</div>
<p><strong>Lists and tables</strong>: 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.</p>
<p><strong>Diagrams and images</strong>: 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 <strong>Show pictures</strong> dropdowns is a suboptimal user experience. It's an additional click for little gain.</p>
<p><strong>Font and presentation layer</strong>: 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.</p>
<p><strong>Admonition overuse</strong>: 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.</p>
<hr />
<h2 id="general">General<a class="headerlink" href="#general" title="Permanent link">&para;</a></h2>
<p>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.</p>
<p>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.</p>
<p>The language scores highly on the <a href="https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests">Flesch-Kincaid Grade Level</a>, 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.</p>
<p>As a reader I get the sense the chapters have been written by different people and the documentation set does not work together.</p>
<p><strong>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.</strong></p>
<hr />
<p><a href="https://gugulet.hu/resume" target="_blank" ><div class="button">See my résume</div></a></p>
<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>
</article>
</div>
<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
</div>
</main>
<footer class="md-footer">
<div class="md-footer-meta md-typeset">
<div class="md-footer-meta__inner md-grid">
<div class="md-copyright">
<div class="md-copyright__highlight">
© Gugulethu Hlekwayo. All rights reserved.
</div>
</div>
</div>
</div>
</footer>
</div>
<div class="md-dialog" data-md-component="dialog">
<div class="md-dialog__inner md-typeset"></div>
</div>
<div class="md-progress" data-md-component="progress" role="progressbar"></div>
<script id="__config" type="application/json">{"annotate":null,"base":"../..","features":["navigation.indexes","navigation.instant","navigation.instant.prefetch","navigation.instant.progress","navigation.tracking","search.highlight"],"search":"../../assets/javascripts/workers/search.e2d2d235.min.js","tags":null,"translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":null}</script>
<script src="../../assets/javascripts/bundle.8ffeb9c9.min.js"></script>
<script src="../../assets/js/loader.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink