Posts by Monica Cellio
Our documentation set includes some diagrams, such as entity relationship diagrams and flowcharts, where text is integral and cannot reasonably be handled in callouts. Our documentation is translat...
You said in a comment that this is for an existing, old show, presumably one with a fanbase. While your listeners have presumably seen it (they're listening to your podcast about it, after all), t...
In the point-of-view culture in my story, all of the women in priestly families have two-syllable names beginning with vowels. (There are reasons for this, but they're completely tangential to my q...
Increasingly often, if you Google for a recipe your search results will be full of long, image-rich blog posts that, somewhere in there, have the actual recipe you were looking for. Many of these ...
It's been decades since I was a kid watching cartoons on TV, and I can still sing some of the Schoolhouse Rock songs. Schoolhouse Rock, for those unfamiliar with it, was a series of short (2-3 min...
We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics --...
Our software documentation set (for a SQL analytics database platform) is large, because SQL and databases have many pieces. Often a single statement, function, or feature will be highly related to...
API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to ...
Names are almost never globally unique. This is true whether the owner chooses or the owner's parents do. Author Alex Feinman even has a note on his web site (.net) saying "looking for the other ...
I see two parts to your question: signaling that 18 is significant, and signaling why it is significant. Assuming that you'll have Jewish readers too, don't skimp on the first part -- you want to ...
We use Madcap Flare for a large documentation set, with HTML output. (Flare source is a very HTML-y XML with some Flare-specific additions.) We use git for source control and new work is done on ...
If you don't provide a hint, then readers will know only that somebody requested a meeting and that's considered an emergency. If you want to convey something about the nature of the organization ...
The guiding principle in my experience is: put the link where the reader needs the referenced information. Examples: "This interface is like Somebody Else's Thing (link, or make SET a link itsel...
Regardless of what you're writing, if you use an archaic form readers will notice, and if you use an archaic form only once and not everywhere it applies, readers will notice that too. If you're d...
You avoid it by showing us a whole, three-dimensional character with attendant complexity. Doing great things is not about one thing. Your character has a mix of traits, talents, interests, incli...
The first step is to work out some style guidelines among yourselves. Agree on what style you want the finished product to follow. Because this is a project among friends rather than, say, a corp...
I sometimes post photos on my blog, like when I'm blogging about food. I've been shrinking the huge pictures my phone takes down to a size that fits more reasonably in a browser window -- my brows...
This answer covers a single work like a paper well, and what it says applies to larger works too. Correctness and clarity are the most important factors in any technical work. For larger works, su...
Full names and arbitrary names are good solutions to the question you asked. To address the question behind the one you asked -- the implicit "superiority" in ordering -- write examples that don't ...
Plagiarism would be taking exact text from the various game manuals and representing it as your own. So don't do that. But you probably weren't going to anyway, because you want to tell a story,...
I've got nothing on shadowing (I suspect that's a very hard sell), but for asking questions, there are two (non-exclusive) approaches that I've seen and occasionally been part of (on both sides). ...
How you structure a code review depends on the tools you're using and the level of scrutiny that was requested. Instead of giving you an exact template, therefore, I'll address the different types...
These are songs, and we learn songs differently from spoken language. Have you ever found yourself singing along to a favorite song in a language you don't even speak, but you've listened to the r...
This answer provides a lot of good information. I want to augment it, not compete with it. Over time, many organizations develop templates for various documents (design, functional spec, test pla...
The light is inside him; it just needs a path out. Not a big gaping doorway that opens all at once, but small tendrils. Think "many drips carve a rock", not sudden change. How do you do that? I...
