Technical documentation that doesn’t include definitions amazes me. How can you be sure your audience is following along, especially when you’re using specific jargon? Defining terms in context works so long as you have a way for the user to come back to the context, to be reminded of the definition. Recently I hit an… Read More What are we saying here?
The text of an executive order crossed my screen and left me muttering and not (just) for political reasons. The order fails to define terms and consequently is self-contradictory. …The Fourteenth Amendment has always excluded from birthright citizenship persons who were born in the United States but not “subject to the jurisdiction thereof.” …Among the… Read More Executive Order Needs a Bigger Glossary
Writing about technology, I must use the correct terms to avoid losing or, worse, confusing my audience. While working on my current assignments, a non-technical SME confused the terms access and permissions. No one’s head exploded (though I think in one case, it was a near thing) and we were able to understand the very… Read More Access, Permissions, and a DEI Plug
We’ve all encountered Help media that is, shall we say, less than helpful. Videos that maintain a far zoom when a close up of the part of the project currently being worked on would be more informative. Help documentation without screenshots that also doesn’t give any directional information. It leaves the reader asking, How do… Read More Writing process documentation or, how to do the what now?
Thinking today about Internal Service Level Agreements (SLAs) or, as the Dev Lead might say when approached on the subject, “the what now? You mean, my employment contract, right?” The answer to that is, “Technically… okay, no.” An internal SLA is the commitment between the provider and the consumer, as with an SLA between a… Read More Internal SLAs
Technically Writing 