article

day

techwriting-global.com

• Back ↩︎

Software Documentation
(API, Guides)

Queries contain keywords and terms that indicate what a user is looking for. However, these keywords are not universal. They vary based on your catalog and products.For a clothing company, the word “red” in a query likely indicates that a user is searching for red articles.For a film database, however, “red” is probably unrelated to a color category.Once you determine the intended effect of specific query terms or phrases, you can dynamically change your users’ results when their search matches those terms. Algolia lets you configure this using Rules.x-algolia-api-key
string header requiredYour Algolia API key with the necessary permissions to make the request.Permissions are controlled through access control lists (ACL) and access restrictions.curl --request POST \
--url https://id.algolia.net/1/indexes/ALGOLIA_INDEX_NAME/query \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-algolia-api-key: ALGOLIA_API_KEY' \
--header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID' \
--data '{"params":"hitsPerPage=2&getRankingInfo=1"}' `

techwriting-global.com

• Back ↩︎

Glossary

A Digital Factory is not a dismal brick building on a deserted highway. It’s not a noisy, machine-driven echo chamber with union workers on 24/7 shifts. And it’s not virtual.A digital factory is real, comprised of a group of extremely productive and motivated experts who are on the same digital page as their management.These multi-talented experts—designers, marketers, engineers, and project managers—function as a team, much like an in-house consulting agency. They work with their organization’s executives and business teams while taking full ownership of and delivering digital assets, including content, web pages, and mobile apps. Like any factory, a digital factory operates as a single unit, developing ideas and products from start to finish. This effort ensures that an organization's digital software and channels are fully branded. They also produce competitive features and a great user experience.A factory's members use many types of collaborative software. For example, they use Figma for designers, GitHub for developers, CMS platforms for content, and Slack for communications. They also use project management tools. Some apps also help by providing business data (e.g., CRMs, ERPs) and insights (analytics). In general, they use any best-in-class app that helps them work together quickly and efficiently.

techwriting-global.com

• Back ↩︎

Technology Blogs

Supervised Machine LearningIf you feed a computer 1000s of images of dogs and cats, labeled correctly as “dogs” and “cats”, an ML algorithm can eventually learn what a dog or a cat looks like. It does this as follows: it breaks down images into pixels, converts the pixels into numbers (which represent colors), plots these numbers on a graph, and then discerns patterns typical of a dog or a cat image. Some pixels might contain patterns resembling a nose (wedged or snout) or ears (pointy or droopy).Labeling every image as “dog” or “cat” helps the computer know if its guess is right or wrong and by how much it is wrong. If it’s wrong, it reprocesses the images, sharpening its pattern-detection until it minimizes the error in its judgment. The process is finished when the computer can predict — with a very high likelihood of truth — that the image is a dog or a cat.From Supervised to Unsupervised LearningThe just-described dog-and-cat image recognition algorithm is called supervised learning, meaning it uses image labels (or other metadata) to learn. However, labeling is tedious – and impossible: we can’t label every object in the world if we want our machines to understand the world. For example, annotating dogs and cats is easy, but how about annotating the prognosis in a medical report? So, we need an algorithm that can learn without explicit labeling. We need to teach computers to learn unsupervised – that is, unlabeled. This significant change in machine learning affects all aspects of the ML modeling process.

techwriting-global.com

• Back ↩︎

Content marketing & Thought leadership

You can build a marketplace with a desk and two chairs, with an open laptop. In our scenario, there are two entrepreneurs with a talent for selling other people’s products. One is a sharp-witted promoter of local artists and dealers who started the business and built it up with her winning personality and business smarts. Her partner, an engineering wizard, built the software that enabled their marketplace to become a mecca for local artists and dealers.For a long time, the engineer had been thinking about going online. She developed a powerful software ecosystem with a beautiful web design, creating the ideal user experience for a locked-in public eager to discover hard-to-find art and antiques.As their online business grew, its technology and business merged. Merchandising and content discovery combined with simplified software processes for ordering and delivery. The platform offered an ideal search and discovery experience for the high demands of both consumers (demand) and vendors (supply). With talent and constant iteration, these women built their digital marketplace into the obvious one-stop shop for regional art and antiques.All that with a desk and two chairs, now crafted in ebony. Contact us if you want us to help you set this up.

techwriting-global.com

• Back ↩︎

Ghostwriting for executives

Technology continues to transform commerce. The most recent example is visual shopping, a fast-growing online functionality that leverages the technologies of image recognition and machine learning to create a powerful visual search-by-image and discovery experience.Smartphones and online photo sharing, combined with machine learning and image recognition technologies, power visual search. Technically, visual search is called image recognition, or more broadly, computer vision, but more commonly, it’s known as search-by-image and reverse-image search.The consumer could type out a very detailed description, such as “chandelier gold antique candlecups chains pendalogue”, but this relies on great search skills. They will need to combine common sense words (chandelier, gold, antique) with more technical terms (candlecups, chains, pendalogue).But there’s a good chance that such a detailed and perhaps incorrect set of words will get no results – even if the item is available on that website.Enter images. With image recognition, companies can build applications that match the above photo with all the same photos and descriptions in its search index. The best ML models can achieve high levels of accuracy (92% and 99% in some cases), where every significant detail matters, thus enabling the search engine to detect exact matches.

techwriting-global.com

• Back ↩︎

internal code documentation

There are at least seven layers between the data in the iCrawl database and the information that appears in the iSee and iKnow APIs. Seven is the lucky number, but there are, in fact, many ways to enumerate the quantity of layers. We can say there are actually ten or fifteen layers, because within each layer there are a number of sub-layers of equal importance that are significantly different from the others, warranting separate treatment. Or we can say there are really only two layers: the Data/Business layer and the Presentation Layer.But the question of how many layers there are is too abstract for our purposes. What matters is that there are seven major back and front ends that act as interlocking points along the data flow.These layers build upon the previous layer – combining fields, adding new data, and reformatting information; the layers are sometimes redundant, with nothing really changing in the exchange, the only purpose being to wrap functionality or decouple iWalk from the iCrawl database. In all cases, however, the layers are set up to be followed in a very precise, linear fashion with the momentous task of getting data from iCrawl (Part 1) into the front end (Part 2).The first five layers – Part 1 – require a good understanding of iCrawl’s data and its functional concepts. The final two layers – Part 2 – require a good understanding of iWalk functionality and web development.Each layer plays a small but significant role in the overall process. Be aware that each layer accomplishes its task in a different way: a different way of thinking, a different vocabulary, a different technology, a different set of data, and a different way of representing that data.This complexity requires patience, concentration, creativity, and adaptability, along with an ease in a number of distinct skills – both functional and technical. And time – there is an estimated two-year learning curve. So, be patient with the process. At times, this document may slip into criticisms of the iWalk Framework or frustrations with its code. These are personal to the writer and are not intended to be merely critical: they are added constructively to inform the reader that the learning process is difficult for everybody.

techwriting-global.com

• Back ↩︎

AI / LLM for technical content

Do I use AI? Yes and No.

TL;DRI primarily use AI as a research tool and for editing my own text. However, some companies encourage more extensive use.In those cases, I still do the actual writing myself, but AI assists the process, while never generating content wholesale.My workflow: First, I write a rough draft by hand, drawing from my research notes. Then I feed the draft into an LLM (ChatGPT, Claude) as a prompt. Finally, I revise the generated output to correct errors, cut fluff, and eliminate clichés—making sure the final piece doesn't read as AI-generated to either readers or search engines. I also use AI to match tone and branding.DETAILSAI/LLMs have changed everything, and yet little has changed.Consider the standard content cycle:
- Define the subject
- Research and outline
- Write the first draft
- Perform eep edit and re-draft
- Proofread
- PublishHas AI changed that? Not at all. We still need all these steps.But clearly something has changed.The difference is that AI could conceivably do every one of these steps with little human intervention.Or is that really the case?Consider how AI would define a subject. Do we just ask AI to find a subject?No, we master the PROMPT. We prompt and rework the prompt until we decide on the best subject to write about.And then we research. We mix our experience, Google searches, and numerous AI prompts to conduct our research.And then we write.Here's my writing process: I usually write as I research, taking lots of notes. And then I convert my notes into a first draft.And then, here's the most significant change: I now use my draft as a prompt. I then rework the output, removing AI errors, fluff, and clichés. I also make sure it’s not detected as AI.Writers must know how to combine their craft and experience with the invaluable insights that come from AI tools.ConclusionSo, little has changed—we need writers who continue to master their craft while also learning to work with AI. How they balance the use of AI with their own work is what separates the modern writer from the old school.*Note: On the other hand, not being a visual artist, I use Reve and other image generators for all images and diagrams.