Glorified Plumbing

I am. Actually, I am currently developing two glossaries. Yes, they overlap, but I have a good reason for that. One glossary is a companion to this blog. The second is for a company I am currently engaged with. Both here and there, I use a lot of jargon, buzzwords, industry-specific terminology, and, worse yet, acronyms and abbreviations. The audience includes cross-functional teams both at the company and among this blog’s readers. We all have different backgrounds, and as a result, we have a different vocabulary. A glossary is a great way to introduce a concept, provide a quick reminder, and even disambiguate an overloaded term.

I have to keep the company’s internal glossary private, as some of the terms, project names and code words are proprietary, which are trade secrets and not for public dissemination.

Can’t I just Google the term?

Yes, you can. Probably.

There are excellent resources out there that define words and acronyms. Wikipedia is a great example, with its encyclopaedic format. I am too cheap to pony up for a licence to the OED (Oxford English Dictionary), but I do use Merriam-Webster’s online dictionary. I know, for a Brit, that’s crazy. Neither of these are complete, though. Notice how Wikipedia does not yet have a disambiguation link for Sketchbook in the context of Arduino IDE project folder structure.

There is a lot of domain-specific information that is defined on the web; I found this article at Programming Electronics Academy before I found Arduino’s official definition of Sketch (not Sketchbook!) A search within the Arduino.cc website pulled up a list of blog posts, forum discussions, and tutorials with the keyword “sketchbook” but did not link to a clean definition like we go for Sketch. A Sketchbook, in these terms, is a folder that contains several Sketches, which are, in turn, software projects.

Why am I so concerned with how Arduino defines Sketchbook? Right now, I am with a team of industry veterans. We are used to working directly with vendors SDK (Software Development Kits) and HDK (Hardware Development Kit) from companies like Atmel/Microchip, NXP, and ST. We have mixed HW, SW and FW (firmware) development backgrounds. We have seen the growth of the SBC (Single Board Computer) industry targeted at hobbyist usage and prototyping. Key players include Adafruit, Raspberry Pi and Arduino. Some bring their own IDEs and work environments. Some work with more generic toolchains like PlatformIO. Naturally, we want to know how we can leverage this new world to our advantage. We have some catching up to do, and our new project seems like the best place to dip our feet into this world.

As part of the new project, I have been evaluating development platforms. I am also setting up the code repository and looking at how we should manage 3rd party libraries so that all our team members are using the same versions with the same specialisations. In writing my report, I had to use the Arduino parlance. These were new terms to me, and I know they will be new to several other team members. I can help them come up to speed if I can provide succinct definitions. That is where a glossary excels. The team will not have to remember which report the definition appears in, they can go straight to the glossary, and there it is.

And then, what about internal vocabulary? The company’s internal language. I worked at a company which had a data alligator. I was stumped, unsure if this was an industry term I had not yet met. It was not defined on the corp wiki. Turns out it was an inside joke. It was simply a data aggregator. I added it to the wiki while still in the meeting where I learnt the definition.

My “trusty” research assistant

I’m leaning more toward having AI help me with mundane chores. A glossary of industry-standard and vendor-specific terms for internal use is a valuable resource. Though not a waste of my time (I only have to explain once and not once to each and every new hire), I have a full plate, and glossary writing can take 10-15 minutes per term for the easy ones. If only I had an intern. I don’t yet, but I do have ChatGPT.

It took about half an hour to configure ChatGPT to make a Glossary Generator. This link is to a custom ChatGPT 4.0, so you can play if you have a subscription. If you don’t have the subscription, it will be out of reach to you. The specifications I gave guided the format so I would get a uniform look and feel.

Create an entry for the glossary.

From a given word or acronym, write a 3-6 line definition based on best knowledge.
Challange any ambiguous term, asking for which discipline, domain or context the definition should relate to.

The format of the response should be 

1. a level two heading that is the keyword or acronym being defined.

2. THe domain, such as 
```
**Domain:** Software engineering.
```
or 
```
**Domain:** Intelligent Traffic Systems.
```

3. a An indication if proprietary only if it is so, and if so who from, for example I2C would have the line
```
**Proprietary:** NXP (originally Philips Semiconductor).


3.b An indication of origin if tied to a specific vendor/source.  Such as Arduino  
``` 
**Origin:** Arduino, SBC vendor
``` 
or Wiki would be
```
**Origin:** Hawaiian, wiki meaning quick
```


3.c any other tagged field that makes sense to the GPT ( I can always edit if I don't like).

4. A concise definition, 4-5 lines maximum.

5. A citation link if applicable, again the I2C example

```
*Links:*
[Specification UM10204](https://www.nxp.com/docs/en/user-guide/UM10204.pdf)


The resultant definition should be presented as a code block containing GitHub Markdown. Any formula can be in LaTeX.
Each sentence to be on a new-line in the markdown.
Double new lines indicate paragraph breaks.

Key terms and special words to be enclosed in single back ticks, as in a code sample.
e.g.
```
`Visual Studio Code`
`Eclipse`
```

The result is in markdown. I asked for a definition of Glossary.

## Glossary

**Domain:** General

A `glossary` is a specialized list of terms with their definitions, often found at the end of a book, document, or within a specific field of study or practice. It serves as a reference to help readers understand specialized or unfamiliar vocabulary. Glossaries are crucial in academic texts, technical documentation, and various fields where specific jargon is used,

And when you see this in its final form

Glossary

Domain: General

A glossary is a specialized list of terms with their definitions, often found at the end of a book, document, or within a specific field of study or practice. It serves as a reference to help readers understand specialized or unfamiliar vocabulary. Glossaries are crucial in academic texts, technical documentation, and various fields where specific jargon is used,

If you read my specifications, you can see I anticipated ambiguity, and ChatGPT honours my wish to be challenged. I don’t want the old AssUMe issue. (Assumptions – make an ass out of you and me.)

I thought it was a “Task Control Block”; tasks and threads are terms that are sometimes the same and, at others, distinct. I know, let’s run thread through the generator.

Thread (in Multi-core CPU Context)

Domain: Computer Architecture

In the context of multi-core CPUs, a thread refers to the smallest sequence of programmed instructions that can be managed independently by a scheduler, which is typically a component of the operating system. Multi-core processors can execute multiple threads simultaneously, one per core, enhancing performance through parallelism. Additionally, technologies like Intel’s Hyper-Threading allow a single core to execute multiple threads concurrently, further improving efficiency and throughput by making better use of CPU resources.

Thread (in RTOS Context)

Domain: Real-Time Operating Systems

In the context of a Real-Time Operating System (RTOS), a thread (often called a “task” in RTOS terminology) is a basic unit of CPU utilization that includes the thread context, program counter, registers, and stack. Threads within an RTOS are designed to run independently and are scheduled based on their priority, timing constraints, and the system’s real-time requirements. This allows RTOS-based systems to manage time-critical tasks efficiently, ensuring that high-priority tasks meet their deadlines, which is crucial in embedded systems where timing predictability and system reliability are essential.

From this example, you can see the value of using ChatGPT. Could you type all that in 30 seconds?

Don’t trust those yet. I can bless the RTOS version; that’s my bread and butter. It’s good enough for my HW and QA engineers and more than enough for my project manager. If the CFO hears the term in an all-hands and gets curious, he can see our blessed version.

The multi-core version doesn’t sound quite right to me, but it is credible. Before I add that definition, I will read at least the intro to the Wikipedia article.

Uniform approach

Company wikis have “too many voices”.

One colleague, let’s call him Mike (since that was his name), gave eloquent essays about everything. He actually had a fun style, and it would bring some levity to dry subjects. However, his style would lead to wordy, sometimes distracting, prose. Pots and kettles, I know. This blog is not a glossary or how-to article, so I’m allowed some waffling.

We had another very minimalist team member. In their style, an acronym might be expanded to the words, but outsiders were frankly left outside when those words were domain-specific.

As a quick reference, I believe there should be a standard format. In your dictionary, the word is followed by the type noun, verb, adjective, and so on. Then probably pronunciation, and then definition. You don’t have to get halfway into a paragraph to see it is an old English adverb. You can quickly scan and grok the information.

This is why I have the term followed by a domain, maybe origin, then definition, and in lieu of “see also” or “further reading” simply “links” if available.

Arduino

Domain: Embedded Systems and Electronics.

Origin: Italian, named after a bar in Ivrea, Italy, where the founders of the Arduino project used to meet.

Arduino refers to an open-source electronics platform based on easy-to-use hardware and software. Arduino boards are able to read inputs – light on a sensor, a finger on a button, or a Twitter message – and turn it into an output – activating a motor, turning on an LED, publishing something online. Users can tell their board what to do by sending a set of instructions to the microcontroller on the board through the Arduino programming language (based on Wiring) and the Arduino Development Environment (based on Processing). Arduino was designed to be accessible to beginners and flexible enough for advanced users, ideal for rapid prototyping and educational projects.

Links:
Arduino Official Website

I think you will understand my motivation here.

How much detail?

This is a very good question. Should the glossary be only just enough to jog you forward into your follow-up learning? Maybe it should be self-contained, with no dependencies? I specified 3-6 lines and had reasonably sized results. Maybe they are too long. If I capped them at 50 words, well, we get entries like this.

Arduino

Domain: Electronics, Embedded Systems

Origin: Arduino, Open-source Electronics Platform

Arduino is an open-source electronics platform based on easy-to-use hardware and software. It’s designed for artists, designers, hobbyists, and anyone interested in creating interactive objects or environments.

This would probably be more appropriate if I were putting it in a book. It is succinct. What else do you need to know? Since I have a wiki, I will allow the longer definitions.

How about a one-liner?

Arduino

Domain: Electronics, Embedded Systems

Arduino is an open-source platform for building electronics projects, encompassing both hardware (microcontroller boards) and software (IDE).

That does the job, but see how we are denied some of the context? We no longer see that it is “easy to use” and more tailored to “hobbyist/non-engineer”.

Just for me

You might not think you need a personal glossary, but ask yourself this. Do you forget things? Do you jot down notes and definitions in the margin of your notebook? Paper notes are hard to keep curated. Do you index all your notebooks, or just know vaguely when something happened?

I was challenged in an interview once, my résumé contained the term SIMD. Three months later, I worked out it meant “Single Instruction, Multiple Data”. That didn’t help in the phone screen for that job, and I removed the term from the résumé before I applied elsewhere. If I’d kept track of terms and work projects better, I would have known.

I believe you should keep notes. Maybe you could use 4×6″ index cards or an A5 ring binder, and maybe keep it in Google Sheets. Mine is going into GitHub because I am more active there than Confluence, and WordPress (hosting this site) does not have a Wiki at this subscription level.

Summing up

I find glossaries an invaluable resource for bridging knowledge gaps. They are the gaps between disciplines in cross-functional teams, onboarding new hires, mentoring juniors, and disseminating new truths to older team members. They also act as a reminder of things you once knew.

Glossaries not only define but disambiguate. Many words are overloaded in the technology industry; a local glossary provides the definition appropriate to the context and use case of the organisation.

Glossaries can be as rich as you want. They benefit from brevity as they become more approachable and digestible. If they are too brief, they become nothing more than a stepping stone to a different source of truth. Finding a balance between the extremes is a tricky path to navigate and somewhat subjective.

A regular structure, much as you see in a dictionary, can ease the digestion of the information. Other examples where you see regular layouts are recipe cards, baseball cards, and product comparison websites.

Writing glossary entries can be time-consuming. Grow the knowledge base as needed. Corporate wikis evolve because when a user does not find a term, they will add the definition themselves. With this organic approach, there will be no unread entries and, eventually, no gaps.

More than one author can lead to more than one style, so care must be taken. A well-curated resource is easier to use and will be used more.

Automating the task may be possible for defining industry standard terms. I have been using a chatbot. Remember, you can use AI to generate an entry, but you have the obligation to validate it. Alternatively, you can write the definition, have AI fact-check you, and restructure it to fit the format. As time goes by, the AIs will be more reliable. Today, in early 2024, we are still learning how to use them.

So, do you have a favourite format for a glossary? I’d like to know how you are maintaining yours, I am always happy to learn new ideas, and maybe I can improve my work.

---

About this weeks cover image

I used a ChatGPT “Tech Writer Mentor,” which I use as a reviewer of my blog articles. After discussing the article, I gave the prompt, “There are plenty of code samples, example definitions in the text. No diagrams. Can we get a headliner image?” and the result follows. Of course, we iterated to get one I preferred.

Let’s craft a visual that encapsulates the essence of your blog article—a representation of glossaries bridging the gap between complex technical jargon and accessible knowledge. The image will feature a visual metaphor: a bridge constructed from pages of a glossary, spanning over a chasm filled with jumbled letters and technical symbols. On one side of the bridge, we’ll have a diverse group of professionals representing cross-functional teams. On the other side, clear, understandable language symbolized by a light bulb illuminating a path forward.

Image Description for DALL-E:

Create an image that illustrates a bridge made out of pages from a glossary. The bridge spans over a chasm filled with jumbled letters and technical symbols, representing the confusion often caused by industry-specific jargon. On one side of the bridge, a diverse group of professionals (engineers, designers, and developers) stands, looking towards the other side, where a giant, glowing light bulb illuminates the path forward, symbolizing clarity and understanding. The background is a mix of digital and traditional elements, highlighting the blend of technology and learning. The overall tone of the image is optimistic and enlightening, showcasing the bridge as a solution to navigating the complexities of technical language.

Let’s proceed with creating this image.

The headliner image for your blog article has been created. It visually represents the concept of glossaries as bridges over the chasm of technical jargon, leading towards clarity and understanding. This image should serve as an engaging introduction to your article, capturing the essence of bridging knowledge gaps with glossaries.