Posts by Monica Cellio
If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and...
I received a response from Flare's technical support. There was a bug in Flare's git integration in some older versions (at least 2019r2; not sure how much farther back). This bug was fixed in Fl...
There's no quick or complete fix, but the following things have worked for me. Plant the seeds early First, involve those new hires. When everything is new to them, you are in a better position ...
That's a bug, yes. :-( Thanks for the report. As a workaround, if you choose[1] the "insert" button instead of using "enter", it inserts the link into the markdown and puts you back in the editor...
Like this answer, I don't think you need to use first-person to get into a character's head. I want to focus a little more on how to do that in omniscient third-person. An omniscient narrator can...
We need to flesh this out, but the idea I have in my head, and that I recall discussing on the forum thread (which I haven't gone back and reread yet), is that in addition to votes we'll allow peop...
This is now configurable and I've moved Meta to the last position on this site.
A core principle with citation is: if you say it's from source X, it must be exactly what's in source X. Not a summary. Not a translation. Not a refactoring. By citing a source you are invoking...
IDE-like tools exist for writers. Scrivener is a powerful general-purpose tool (also with questions here). Madcap Flare, aimed at technical writers, has good support for updating links, defining "s...
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' ...
As this answer says, it's important to state your assumptions, whatever they are. Sometimes there just isn't enough data, though, and I understand your question to be about what to do in that case...
While it's possible to expand a short story into a novel (c.f. Ender's Game), what seems more common in my experience (citation needed) is for the short story to become one part of a larger novel. ...
Elves and dwarves are all over fantasy fiction. Here's one compilation found by Googling "fantasy novels with elves". They are generic mythological creatures. If anything these tropes are overus...
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...
"Private" doesn't mean just one recipient; it just means "not public". When you throw a by-invitation party in your home it's a private affair even if there are 50 people there. Email is the same...
I've done it both ways, and have found that a hybrid approach ends up working best. Doing it at the end means you can focus just on indexing (not writing). You're more likely to be consistent in ...
The reader needs a connection when transitioning into the flashback. That transition can be either external or internal. By external, I mean introducing the flashback. In this case, the reader kn...
I've done this sort of thing as part of evaluating technologies. It's usually cast as an evaluation, covering both benefits and weaknesses, rather than just weaknesses. I suggest getting clarificat...
This is a challenging specialization to capture in a job title, which is why my LinkedIn tagline says "speaker to programmers". But that doesn't work as a job title at any but the edgiest startups...
Our documentation set includes some diagrams where text is integral and can't be handled in callouts, like flowcharts and entity relationship diagrams. Our documentation is translated, so these di...
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...
