Posts by Monica Cellio
What you write depends on your audience. API reference documentation -- the output of tool- like Doxygen -- is usually for the users of that API. Such externally-facing documentation focuses on t...
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 ...
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 ...
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 ...
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...
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...
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...
One way to keep it from taking over your story is to make it unexceptional. Quite literally. Kem is nonbinary. If Kem, other characters, and the narrator don't make a big deal out of that, don't...
I've found that the main key to unfamiliar words -- and this applies to jargon in technical writing as much as it does to foreign or made-up words in fiction -- is density. The example in the XKCD...
I was the editor of my university paper back in the day. Chris Sunami's answer is right; university newspapers are produced by amateurs, people learning the trade (who might not even be taking jou...
I am an experienced technical writer specializing in API documentation. In my experience, in order to be successful a technical writer needs enough technical aptitude to (1) understand the users' ...
I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google). The doc set has a glossary, which pre...
In doing research, whether online or offline, there are two types of assertions you can encounter: supported and unsupported. (Just like here on Stack Exchange!) An unsupported claim isn't worth ...
IEEE uses a style that is common for journal articles and academic works. The citation is the full "description" of the work -- author, title, date, publication, etc. The document you linked desc...
The convention in scientific writing, at least in the hard sciences, is to avoid "I" even for single-author papers. I suspect (but can't prove) that this is why you see so much passive voice in su...
Speculative stories about God, or gods, can show up in the realm of speculative fiction, science fiction, or fantasy. Consider the following examples: Some of the stories in Wandering Stars, ed....
You can cast it as an early report on your beta launch, or as a preview of your forthcoming launch. Assuming that you're restricting it now so you can work the kinks out before spreading more wide...
You appear to be writing your "the story so far" from the point of view of an omniscient narrator, hence your concern abut lying. Instead, describe events through a character lens. You can do thi...
A citation is a pointer to a source. While a URL is technically that, when universities say "citation" they mean something following a formal citation format. A citation typically includes an aut...
PDFs use a fixed layout that doesn't scale with the device or window size, so they're not as friendly for smaller screens. Some people do read PDFs on some phones, though -- some screens are prett...
It depends, but probably you want the distributed approach where the chapter on X tells you everything you need to know about X, even if some of that is only relevant if you're using feature Y. Ho...
I am not a lawyer and this is not legal advice. First, check any license terms that accompany Company S's documentation. They might have published it with the intention that other vendors will in...
