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...
Writing positively about yourself can be hard. It feels like bragging, which feels rude. What I've found helps is to frame it as a specific marketing project. It's not that I would go around boa...
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...
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...
One of our community members, Paulster2, has created some ads and submitted them on SE sites where we've advertised in the past. These are "community promotion" ads, meaning the SE communities vot...
I endorse Evil Sparrow's answer. If, however you must lead with the old man for some reason, you can return from the room back to him with a paragraph break. Paragraph breaks are (small) disconti...
It depends on how formal the context is. If you're writing a short blog post about getting started with a new game, "you'll" probably won't be out of place. If you're writing a tutorial as part o...
This depends in part on who your audience is, as already noted. It also depends on what kind of editorial support you'll have and on what your goals are. I've seen lots of work, both drafts and p...
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...
A link to the name is generally expected to link to the person, not to an article. I generally agree with @Craig Sefton, except that I would make "claims that pigs can fly" the link and not just "...
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...
Why not test the hypothesis, starting with the negative test? You are unhappy in your current career. You have some background but nothing official. A BA in English might or might not be a meani...
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...
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 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...
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 ...
The MLA doesn't have a definitive statement on this. In an entry about citing speech bubbles from comics they show an example that includes only the author, but the book itself doesn't credit an a...
I've worked on a few doc sets like that. While API reference documentation is one case where you see this problem, the problem occurs at the "module" level too. Your question is about microservic...
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 ...
I think you're being tripped up by some mistaken impressions. First, you suggest that ungrammatical and/or persuasive writing is "creative". Maybe some of it is, but that's hardly the definition ...
