diff --git a/.checks/pre-push b/.checks/pre-push index 98a9119..a46a9d5 100755 --- a/.checks/pre-push +++ b/.checks/pre-push @@ -9,6 +9,9 @@ RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m' echo -e "${GREEN}Running pre-push checks...${NC}" +# Start time tracking +START_TIME=$(date +%s) + # Setting paths REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)" CONTENT_DIR="$REPO_ROOT/content" @@ -22,11 +25,11 @@ rm -f "$LOG_DIR/*" # Cleanup function cleanup() { - trap - EXIT INT TERM - if [[ -n "${SERVER_PID:-}" ]] && ps -p "$SERVER_PID" >/dev/null 2>&1; then - kill "$SERVER_PID" >/dev/null 2>&1 || true - for _ in {1..30}; do ps -p "$SERVER_PID" >/dev/null 2>&1 || break; sleep 0.1; done - fi + trap - EXIT INT TERM + if [[ -n "${SERVER_PID:-}" ]] && ps -p "$SERVER_PID" >/dev/null 2>&1; then + kill "$SERVER_PID" >/dev/null 2>&1 || true + for _ in {1..30}; do ps -p "$SERVER_PID" >/dev/null 2>&1 || break; sleep 0.1; done + fi } trap cleanup EXIT INT TERM @@ -86,8 +89,9 @@ if command -v markdownlint-cli2 &>/dev/null; then MD_FILES="$(git diff HEAD~1 HEAD --name-only --diff-filter=ACM | grep -E '\.md$' || true)" if [[ -n "$MD_FILES" ]]; then echo -e "${GREEN}Running markdownlint...${NC}" - echo $MD_FILES | xargs markdownlint-cli2 >"$LOG_DIR/markdownlint.log" 2>&1 || { - echo -e "${RED}markdownlint-cli2 failed. See $LOG_DIR/markdownlint.log${NC}"; exit 1; } + echo "$MD_FILES" | xargs markdownlint-cli2 >"$LOG_DIR/markdownlint.log" 2>&1 || { + echo -e "${RED}markdownlint-cli2 failed. See $LOG_DIR/markdownlint.log${NC}"; exit 1; + } else echo -e "${YELLOW}No committed Markdown files found. Skipping markdown check.${NC}" fi @@ -100,8 +104,9 @@ if command -v vale &>/dev/null && [[ -f "$REPO_ROOT/.vale.ini" ]]; then echo -e "${GREEN}Running Vale...${NC}" VALE_FILES="$(git diff HEAD~1 HEAD --name-only --diff-filter=ACM | grep -E '\.md$' || true)" if [[ -n "$VALE_FILES" ]]; then - echo $VALE_FILES | xargs vale >"$LOG_DIR/vale.log" 2>&1 || { - echo -e "${RED}Vale issues. See $LOG_DIR/vale.log${NC}"; exit 1; } + echo "$VALE_FILES" | xargs vale >"$LOG_DIR/vale.log" 2>&1 || { + echo -e "${RED}Vale issues. See $LOG_DIR/vale.log${NC}"; exit 1; + } else echo -e "${YELLOW}No committed Markdown files found. Skipping Vale check.${NC}" fi @@ -114,3 +119,8 @@ if ! command -v zensical >/dev/null 2>&1; then echo -e "${RED}Zensical not installed; cannot build docs.${NC}"; exit 1 fi run_command "zensical build --clean" "$LOG_DIR/zensical-build.log" + +# End time tracking and calculate duration +END_TIME=$(date +%s) +DURATION=$((END_TIME - START_TIME)) +echo -e "${GREEN}Push checks completed in $DURATION seconds.${NC}" diff --git a/.envrc b/.envrc index 53c34e1..8c884b7 100755 --- a/.envrc +++ b/.envrc @@ -21,13 +21,14 @@ fi # Run pip to update packages inside the venv echo "Running pip update..." "$VIRTUAL_ENV/bin/python3.14" -m pip install --upgrade pip -"$VIRTUAL_ENV/bin/python3.14" -m pip install --no-cache-dir --upgrade $(pip list --format=freeze | grep -v '^\-e' | cut -d = -f 1 | tr '\n' ' ') +"$VIRTUAL_ENV/bin/python3.14" -m pip install --no-cache-dir --upgrade $(pip list --format=freeze | grep -v '^\-e' | grep -v '^griffe==' | cut -d = -f 1 | tr '\n' ' ') # Exclude the griffe package for now +# "$VIRTUAL_ENV/bin/python3.14" -m pip install --no-cache-dir --upgrade $(pip list --format=freeze | grep -v '^\-e' | cut -d = -f 1 | tr '\n' ' ') "$VIRTUAL_ENV/bin/python3.14" -m pip freeze > requirements.txt # Update requirements.txt with pinned versions only if installs succeeded if [[ $? -eq 0 ]]; then "$VIRTUAL_ENV/bin/python3.14" -m pip freeze > requirements.txt - echo "Packages updated successfully" + echo "Packages updated successfully" else echo "pip install failed; requirements.txt not updated" fi diff --git a/content/assets/css/index.css b/content/assets/css/index.css index 6d77b17..8579aff 100755 --- a/content/assets/css/index.css +++ b/content/assets/css/index.css @@ -85,16 +85,6 @@ width: 100%; } -.down-arrow { - animation: flash 1s infinite; - bottom: 20px; - color: var(--tertiary-colour); - font-size: 1rem; - left: 50%; - position: fixed; - transform: translateX(-50%); -} - .faces .slide { border-radius: 10px; left: 50%; @@ -137,15 +127,3 @@ footer { .hidden { display: none; } - -@keyframes flash { - - 0%, - 100% { - opacity: 1; - } - - 50% { - opacity: 0.5; - } -} diff --git a/content/assets/css/resume.css b/content/assets/css/resume.css index e69de29..f576546 100755 --- a/content/assets/css/resume.css +++ b/content/assets/css/resume.css @@ -0,0 +1,313 @@ +@import url("theme.css"); + +/***************************** +* RESUME +* Styling for the resume page. +*****************************/ + +* { + z-index: 1; +} + +body { + color: var(--primary-colour); + font-family: var(--general-sans); +} + +.page-menu { + align-items: center; + background-color: var(--background-colour); + color: var(--primary-colour); + display: flex; + flex-direction: row; + font-size: 0.6rem; + font-weight: 400; + justify-content: center; + padding: 10px; + position: sticky; + text-align: center; + top: 0; + z-index: 100; + + &>*:not(:last-child)::after { + content: " | "; + margin: 0 8px; + } +} + +.hero { + align-items: center; + background-image: url('../media/face-1276x1276.webp'); + background-position: center center; + background-repeat: no-repeat; + background-size: 50vh; + display: flex; + flex-direction: column; + height: 100vh; + justify-content: center; + text-align: center; + z-index: -5 !important; + + &::after { + content: ''; + position: absolute; + top: 0; + left: 0; + right: 0; + bottom: 0; + background: rgba(255, 255, 255, 0.95); + pointer-events: none; + } + + .title { + font-family: var(--general-serif); + font-size: 5rem; + font-variation-settings: "opsz" 8; + font-weight: 900; + } + + .metadetails { + border-bottom: 0.5px solid lightgray; + border-top: 0.5px solid lightgray; + display: flex; + flex-direction: row; + gap: 5rem; + + img { + height: 2.5rem; + } + + figcaption { + color: var(--primary-colour); + font-family: var(--general-sans); + font-size: 0.8rem; + font-style: normal; + font-weight: 400; + } + } +} + +#experience { + color: var(--primary-colour); + min-height: 80vh; + + + &>div { + margin: 30px; + padding: 1.2rem; + + li { + border: none; + + &:hover { + box-shadow: none; + } + } + + h2 { + color: var(--primary-colour); + font-family: var(--general-sans); + font-size: 2.5rem; + margin: 0 0 -18px 0; + } + + .company { + font-family: var(--general-sans); + font-weight: 400; + font-size: 1.2rem; + margin: 0; + + span { + font-size: 0.7rem; + font-weight: 400; + margin: 0 0 0 25px; + } + } + + .job-blurb { + font-family: var(--general-serif); + font-size: 1.2rem; + font-weight: 700; + line-height: 1.5; + margin-bottom: 30px; + margin-top: 30px; + } + + .job-achievements { + font-family: var(--general-serif); + + h5 { + color: var(--primary-colour); + font-size: 0.9rem; + margin: 0; + text-transform: none; + } + + p { + margin: 0 0 10px 0; + } + } + } + + .mambu { + background-image: url("../media/mambu-logo-272x263.png"); + } + + .spread { + background-image: url("../media/spread-ai-logo-125x144.png"); + } + + .mambu, + .spread { + background-size: contain; + background-repeat: no-repeat; + filter: saturate(0); + height: 112px; + margin-left: 3rem; + margin-right: 3rem; + position: relative; + + &::after { + background: rgba(255, 255, 255, 0.70); + bottom: 0; + content: ''; + left: 0; + pointer-events: none; + position: absolute; + right: 0; + top: 0; + z-index: -5; + } + } +} + +#demo { + margin: 0 2.5rem; + + .cards { + + .twemoji { + font-size: 3rem; + margin-bottom: 8px; + } + + ul li { + align-items: center; + display: flex; + flex-direction: column; + font-size: 1.8rem; + height: 300px; + justify-content: center; + } + } +} + +#learning { + margin: 2.5rem; + + .cards { + + ul li { + background-color: var(--tertiary-colour); + border: none; + + &:hover { + box-shadow: none; + } + } + } +} + +.prefooter { + align-items: flex-start; + display: flex; + flex-direction: row; + gap: 2rem; + justify-content: center; + margin-top: 1.3rem; + margin-bottom: 0.5rem; + text-align: center; + + div { + img { + height: 1.2rem; + } + } + + div:last-child { + img { + height: 1.5rem; + } + } +} + +.faq-container { + position: relative; + + .faq { + background: var(--background-colour); + border: 2px solid var(--primary-colour); + border-radius: 5px; + bottom: 50px; + opacity: 0; + padding: 20px; + position: fixed; + right: 20px; + transition: opacity 0.3s, visibility 0.3s; + visibility: hidden; + width: 300px; + z-index: 999; + + h3 { + color: var(--primary-colour); + font-family: var(--general-serif); + } + } + + #faq-toggle:checked+.question-icon .icon.question { + opacity: 0; + } + + #faq-toggle:checked+.question-icon .icon.close { + opacity: 1; + } + + #faq-toggle:checked~.faq { + opacity: 1; + visibility: visible; + } + + .question-icon { + align-items: center; + bottom: 20px; + cursor: pointer; + display: flex; + justify-content: center; + position: fixed; + right: 20px; + width: 50px; + z-index: 1000; + + .icon { + font-size: 1rem; + position: absolute; + transition: opacity 0.3s; + } + + .icon.question { + opacity: 1; + } + + .icon.close { + opacity: 0; + } + } +} + +.visually-hidden { + height: 1px; + left: -9999px; + overflow: hidden; + position: absolute; + width: 1px; +} diff --git a/content/assets/js/index.js b/content/assets/js/index.js index 35e03ba..f9162d9 100755 --- a/content/assets/js/index.js +++ b/content/assets/js/index.js @@ -1,5 +1,5 @@ // INDEX.js -// Manages the animations on the home page +// Manages the animations on the homepage document.addEventListener('DOMContentLoaded', function () { // Register the GSAP plugin to use diff --git a/content/assets/js/resume.js b/content/assets/js/resume.js deleted file mode 100755 index e69de29..0000000 diff --git a/content/assets/media/allan-gray-logo-243x160.png b/content/assets/media/allan-gray-logo-243x160.png deleted file mode 100755 index c091495..0000000 Binary files a/content/assets/media/allan-gray-logo-243x160.png and /dev/null differ diff --git a/content/assets/media/berlin-logo-1000x1000.png b/content/assets/media/berlin-logo-1000x1000.png new file mode 100755 index 0000000..955d9c2 Binary files /dev/null and b/content/assets/media/berlin-logo-1000x1000.png differ diff --git a/content/assets/media/face-1276x1276.png b/content/assets/media/face-1276x1276.png new file mode 100755 index 0000000..e5aa6f7 Binary files /dev/null and b/content/assets/media/face-1276x1276.png differ diff --git a/content/assets/media/git-link-512x512.png b/content/assets/media/git-link-512x512.png new file mode 100755 index 0000000..410103c Binary files /dev/null and b/content/assets/media/git-link-512x512.png differ diff --git a/content/assets/media/gugulet.hu-site-logo-350x350.png b/content/assets/media/gugulet.hu-site-logo-350x350.png deleted file mode 100755 index e10893f..0000000 Binary files a/content/assets/media/gugulet.hu-site-logo-350x350.png and /dev/null differ diff --git a/content/assets/media/id-card-icon-512x512.png b/content/assets/media/id-card-icon-512x512.png new file mode 100755 index 0000000..81e537c Binary files /dev/null and b/content/assets/media/id-card-icon-512x512.png differ diff --git a/content/assets/media/languages-icon-512x512.png b/content/assets/media/languages-icon-512x512.png new file mode 100755 index 0000000..3789997 Binary files /dev/null and b/content/assets/media/languages-icon-512x512.png differ diff --git a/content/assets/media/linkedin-logo-512x512.png b/content/assets/media/linkedin-logo-512x512.png new file mode 100755 index 0000000..565690b Binary files /dev/null and b/content/assets/media/linkedin-logo-512x512.png differ diff --git a/content/assets/media/mambu-logo-110x112.png b/content/assets/media/mambu-logo-110x112.png deleted file mode 100755 index 9a9aab6..0000000 Binary files a/content/assets/media/mambu-logo-110x112.png and /dev/null differ diff --git a/content/assets/media/mambu-logo-272x263.png b/content/assets/media/mambu-logo-272x263.png new file mode 100755 index 0000000..5bfa994 Binary files /dev/null and b/content/assets/media/mambu-logo-272x263.png differ diff --git a/content/assets/media/pcvue-documentation-2728x1756.png b/content/assets/media/pcvue-documentation-2728x1756.png deleted file mode 100755 index 9944248..0000000 Binary files a/content/assets/media/pcvue-documentation-2728x1756.png and /dev/null differ diff --git a/content/assets/media/pcvue-print-layout-1573x1433.png b/content/assets/media/pcvue-print-layout-1573x1433.png deleted file mode 100755 index 099c2af..0000000 Binary files a/content/assets/media/pcvue-print-layout-1573x1433.png and /dev/null differ diff --git a/content/assets/media/site-link-512x512.png b/content/assets/media/site-link-512x512.png new file mode 100755 index 0000000..ee24ef1 Binary files /dev/null and b/content/assets/media/site-link-512x512.png differ diff --git a/content/assets/media/technical-writing-icon-512x512.png b/content/assets/media/technical-writing-icon-512x512.png new file mode 100755 index 0000000..567ca1b Binary files /dev/null and b/content/assets/media/technical-writing-icon-512x512.png differ diff --git a/content/assets/media/the-jupiter-drawing-room-logo-119x118.png b/content/assets/media/the-jupiter-drawing-room-logo-119x118.png deleted file mode 100755 index 804ac3b..0000000 Binary files a/content/assets/media/the-jupiter-drawing-room-logo-119x118.png and /dev/null differ diff --git a/content/assets/media/what-is-hmi.gif b/content/assets/media/what-is-hmi.gif deleted file mode 100755 index 88745d4..0000000 Binary files a/content/assets/media/what-is-hmi.gif and /dev/null differ diff --git a/content/assets/media/windhoek-jazz-festival-50s.mp3 b/content/assets/media/windhoek-jazz-festival-50s.mp3 deleted file mode 100755 index ab2985c..0000000 Binary files a/content/assets/media/windhoek-jazz-festival-50s.mp3 and /dev/null differ diff --git a/content/assets/media/yoco-logo-206x206.png b/content/assets/media/yoco-logo-206x206.png deleted file mode 100755 index a73f05d..0000000 Binary files a/content/assets/media/yoco-logo-206x206.png and /dev/null differ diff --git a/content/index.md b/content/index.md index 9bf1004..a52098d 100755 --- a/content/index.md +++ b/content/index.md @@ -41,7 +41,3 @@ title: Home - -
-:fontawesome-solid-chevron-down: -
diff --git a/content/resume.md b/content/resume.md index 4b87371..12e2abf 100755 --- a/content/resume.md +++ b/content/resume.md @@ -2,10 +2,6 @@ description: experience, skills, education. extra_css: - assets/css/resume.css -extra_js: - - assets/js/gsap/gsap.min.js - - assets/js/gsap/ScrollTrigger.min.js - - assets/js/resume.js hide: - toc - navigation @@ -17,21 +13,138 @@ title: Resume -
+ -
-
Gugulethu Hlekwayo
+
+
Gugulethu Hlekwayo
+
+
+
+ City of Berlin logo +
Based in
Berlin, Germany
+
+
+
+
+ ID card icon +
German
Permanent Resident
+
+
+
+
+ Languages icon +
Native English, B1 German,
isiZulu, isiXhosa, A1 Mandarin
+
+
+
+
+ Technical Writing icon +
15 years of
professional writing experience
+
+
+
-
+
+
+
    +
  • +
    +

    Senior Technical Writer

    +
    MAMBU 2021 to 2023
    +
    Promoted to team lead; managing a team of three technical writers.
    +
    +
    Documented the Mambu ecosystem
    +

    Documented integrations, such as payment and compliance services, and the low-code orchestrator that clients used for their flows.

    +
    Documented a command-line interface
    +

    Documented the Mambu CLI for external engineers to connect to the backend directly.

    +
    Assumed leadership role
    +

    Promoted to team lead, which shifted the role into more managerial responsibilities on top of working on documentation.

    +
    +
    +
  • +
  • +
    +

    Documentation Engineer

    +
    SPREAD 2024 to 2026
    +
    Hired as the first Technical Writer to establish the documentation function.
    +
    +
    Built a docs-as-code publishing pipeline
    +

    Built a pipeline that used GitHub Actions to build the documentation site, Vale to lint content, Docker to deploy the site, and shell scripting.

    +
    Established the documentation function
    +

    Socialized the rest of the company to documentation processes and workings; this included onboarding colleagues to edit and use docs.

    +
    Documented the full product range
    +

    Documented the full product range within two quarters. Kept the documentation up to date through two product refreshes.

    +
    +
    +
  • +
+
-
+
+
+
    +
  • + + Technical +
  • +
  • + + Writing +
  • +
  • + + Process +
  • +
+
-
+
+
+
    +
  • + HTML for content and structure +
  • +
  • + JavaScript for interactivity +
  • +
  • + CSS for text running out of boxes +
  • +
  • + Internet Explorer ... huh? +
  • +
+
-
+
+
Self-hosted ForgeJo instance with git repos
+
Link to LinkedIn profile
+
Link to the home page
+
+ +
+ + +
+

Questions and Answers

+

Why did you resign from your last job?

+
Grey / Gray
+

Do you need visa support? Do you have the right to work in Germany?

+
Sesame seed
+

Do you need visa support? Do you have the right to work in Germany (and the EU)?

+

Can you work remotely?

+

Are you able to work on your own?

+

When can you start?

+
diff --git a/content/resume/pcvue.md b/content/resume/pcvue.md deleted file mode 100755 index 344bb4c..0000000 --- a/content/resume/pcvue.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: PcVue assessment -description: An assessment of the documentation provided by PcVue. -hide: - # - toc - - navigation - - search ---- - - - -> ### Brief
-> -> **October 2025**
-> 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](/assets/media/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 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. - ---- - -## 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. - -
- A simple search to find what HMI means -
The search function is slow, fragmented, and can't handle questions
-
- -**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 documentation describing one product. Internal linking helps readers make sense 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. - -
- -- **PcVue print layout** - - --- - - ![The PcVue print layout](/assets/media/pcvue-print-layout-1573x1433.png) - -- **Styled print layout** - - --- - - ![A styled print layout](/assets/media/spread-print-layout-1596x1872.png) - -
- -**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 accessibility for visually impaired readers. Having images under **Show pictures** dropdowns is a suboptimal user experience. 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 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. - -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.** - ---- - -
See my résume
- diff --git a/content/test.md b/content/test.md new file mode 100755 index 0000000..f506814 --- /dev/null +++ b/content/test.md @@ -0,0 +1,29 @@ +--- +title: test +--- + +The HTML specification is maintained by the W3C. + +
+- :fontawesome-brands-html5: __HTML__ for content and structure +- :fontawesome-brands-js: __JavaScript__ for interactivity +- :fontawesome-brands-css3: __CSS__ for text running out of boxes +- :fontawesome-brands-internet-explorer: __Internet Explorer__ ... huh? +
+ + +*[HTML]: Hyper Text Markup Language +*[W3C]: World Wide Web Consortium + + + diff --git a/requirements.txt b/requirements.txt index af4f4b4..fc34519 100755 --- a/requirements.txt +++ b/requirements.txt @@ -3,8 +3,8 @@ colorama==0.4.6 deepmerge==2.0 ghp-import==2.1.0 griffe==1.15.0 -griffecli==1.15.0 -griffelib==1.15.0 +griffecli==2.0.0 +griffelib==2.0.0 Jinja2==3.1.6 Markdown==3.10.2 MarkupSafe==3.0.3 @@ -16,7 +16,7 @@ mkdocstrings==1.0.3 mkdocstrings-python==2.0.2 packaging==26.0 pathspec==1.0.4 -platformdirs==4.5.1 +platformdirs==4.7.1 Pygments==2.19.2 pymdown-extensions==10.20.1 python-dateutil==2.9.0.post0 @@ -24,4 +24,4 @@ PyYAML==6.0.3 pyyaml_env_tag==1.1 six==1.17.0 watchdog==6.0.0 -zensical==0.0.21 +zensical==0.0.23 diff --git a/zensical.toml b/zensical.toml index c04bf27..9ac0374 100755 --- a/zensical.toml +++ b/zensical.toml @@ -3,18 +3,25 @@ copyright = "© Gugulethu Hlekwayo. All rights reserved." docs_dir = "content" extra_css = ["assets/css/theme.css"] language = "en" -nav = [{ 'Homepage' = "index.md" }, { 'Resume' = "resume.md" }] +nav = [ + { "Home" = "index.md" }, + { "Resume" = "resume.md" }, + { "Test" = "test.md" } +] repo = "fontawesome/brands/git-alt" repo_name = "g_it/gugulet.hu" repo_url = "https://git.gugulet.hu/g_it/site" site_author = "Gugulethu Hlekwayo" -site_description = "Gwabini, Bele elide, bhoya benyathi" -site_dir = "./deploy" +site_description = " " +site_dir = "deploy" site_name = "Gugulethu Hlekwayo" site_url = "https://gugulet.hu" [project.extra] generator = false +sitemap = false + +[project.markdown_extensions.abbr] # The Abbreviations extension adds the ability to add a small tooltip to an element, by wrapping it with an abbr tag. [project.markdown_extensions.admonition] # The Admonition extension adds support for admonitions, more commonly known as call-outs, which can be defined in Markdown by using a simple syntax. @@ -52,7 +59,8 @@ pygments_lang_class = true [project.markdown_extensions.pymdownx.mark] # The mark extension allows the use of highlighting in text. [project.markdown_extensions.pymdownx.smartsymbols] # The SmartSymbols extension converts some sequences of characters into their corresponding symbols. -# [project.markdown_extensions.pymdownx.snippets] # The Snippets extension adds the ability to add a small tooltip to an element, by wrapping it with an abbr tag. + +[project.markdown_extensions.pymdownx.snippets] # The Snippets extension adds the ability to add a small tooltip to an element, by wrapping it with an abbr tag. # auto_append = ["content/includes/definitions.md"] [project.markdown_extensions.pymdownx.superfences] # The SuperFences extension allows for arbitrary nesting of code and content blocks inside each other. @@ -73,20 +81,22 @@ custom_checkbox = true [project.markdown_extensions.toc] # The Table of Contents extension automatically generates a table of contents from a document, which Zensical will render as part of the resulting page. permalink = true -[project.plugins.mkdocstrings.handlers.python] # mkdocstrings, which allows rendering API reference documentation from source code. -inventories = ["https://docs.python.org/3/objects.inv"] -paths = ["src"] +# [project.plugins.mkdocstrings.handlers.python] # mkdocstrings, which allows rendering API reference documentation from source code. +# inventories = ["https://docs.python.org/3/objects.inv"] +# paths = ["src"] -[project.plugins.mkdocstrings.handlers.python.options] -docstring_style = "google" -inherited_members = true -show_source = false +# [project.plugins.mkdocstrings.handlers.python.options] +# docstring_style = "google" +# inherited_members = true +# show_source = false [project.plugins.offline] # The offline functionality makes sure that the site search works when you distribute the contents of your site directory as a download. [project.theme] custom_dir = "content/overrides" +favicon = "assets/media/face-1276x1276.png" language = "en" +logo = "assets/media/face-1276x1276.webp" palette.primary = "custom" features = [ "content.action.view", # View source of this page.