Posts by Monica Cellio
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...
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...
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...
We did not find an off-the-shelf solution to this and built our own. I'm not the author and can't release the code, but here is an overview of the approach. Flare versions from 2016 onward support...
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...
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 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...
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...
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...
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...
There are a few relevant factors: Use diagrams when they add value I see plenty of formal writing that includes diagrams -- technical flow diagrams, trend graphs, timelines, resource-allocation c...
One approach is to write separate chapters (maybe alternating, but maybe in this case more from her?) with the writer identified at the beginning of each. A similar approach was taken in the Jumpe...
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...
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...
You can look for other ways to identify the characters. For example: The tall figure stood in the corner, towering over the unmoving skinny figure in the chair beside it. It moved away from th...
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...
In addition to grouping steps that must be done together and teaching troubleshooting, give the user a way to recover -- because sometimes the user isn't going to figure it out and is going to bail...
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...
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...
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'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...
One way to convey time is with signposts: She buried her head in the pillow as she smacked the alarm clock for the third time. He fumbled with his key in the lock, glowering at the burnt-o...
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...
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...
