Posts by Monica Cellio
What goes into your index will be defined by your readers' needs. How will they use your book? Will they come in with knowledge of (and vocabulary from) a related subject? Are they experts or no...
The core of both questions is: why didn't these authors simplify complex sentence structures? It's hard to see how the answers would be significantly different for semicolons versus splitting into...
The Hugo awards are prominent fan awards in the SF&F genre. In 2021, I noticed that all of the finalists in the Novella category are from a single publisher, Tor.com. Novellas have, I underst...
It turns out that "Global" doesn't mean global in Flare. We haven't figured out what it actually means, but to fix this you have to select "XML Editor" from the drop-down menu shown in the screen ...
Edit: fixed. The font face and size make posts too hard to read (and also, I'm now discovering, to compose). The current font face is vertically "squashed"; this is not the Arial or similar that ...
If you are documenting programming interfaces (APIs), look for a tool that generates documentation from comments in the code. This allows you to place the documentation right with the code, and th...
Print publications that are no longer in print are (were) still print publications. You would therefore cite them the same way you would any other newspaper article from a still-extant paper. (Ci...
"Concise" doesn't mean "very short"; it means "no more verbose than it needs to be". In your case, you have needs that establish a minimum length. Trying to fight against that will only lead to f...
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...
The main challenge of having multiple writers is dealing with conflicts -- either you have to lock files to prevent concurrent edits (as Word does), or you need a way to compare and merge changes. ...
In books that go through multiple editions, you will sometimes see "preface to the first edition", "preface to the second edition", etc. In other words, there is precedent for not editing it out b...
I can't call specific examples to mind right now, but I've seen this sort of "wait, the world is not quite as it should be" situation handled by sharing the POV character's inner dialogue as he gra...
I've written manuals under a Scrum process, so I'll describe what worked for my team. I'm going to treat your task as if you're writing a new book. From your description, you'd be replacing the va...
There are different kinds of technical writing, differing in the "technical" part. The logical place for you to start, coming from a programming background like I did, would be with programmer-fac...
This is a hard problem. Unless your company has the resources to do full reviews of all the documentation on each release -- and if they do, I wonder how they stay competitive -- then you are at r...
Start with the style guidelines from Oracle for Javadoc. While those guidelines are written for the Javadoc tool (and the Java language) in particular, the principles there apply to the correspond...
There is no way to absolutely prevent lawsuits; if you're going to cover controversial topics and name names, there's a risk that people will get upset and seek to take action. But there are some ...
Let's break down your illustrative sentence: Users can delete Servers This statement describes a capability -- users can perform this action. I'm hard-pressed to imagine how a different ten...
In the absence of a style guide saying otherwise, your approach is fine. (So is abbreviating to "Fig.", though I prefer to spend the extra three letters and use the full word. It's also consisten...
Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important...
Here's what we do for that. It's not cloud-based, but it is source-control-backed, like (I hope) your code already is. Tools and technologies involved: source control DocBook DTD your favorite ...
Since you're a software developer, I encourage you to think about the book the way you think about a significant application. You (probably) don't just start writing code; you do some requirements...
A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically ...
The second sentence feels grammatically incorrect because it's not a sentence; it's two fragments joined by a semicolon. That doesn't make it wrong, but that's probably why you're reacting that wa...
For inconsequential changes you can just edit it. For anything substantial ("I meant to say I disagree with..."), I've often seen an explicit notation: "Edited to add: ..." "Edit: ...", or the lik...
