Posts by Monica Cellio
The APA style recommends the following for citing anything from web sites (which would include any claim you're reporting from one): New child vaccine gets funding boost. (2001). Retrieved Marc...
I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look...
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...
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 main con is fear of corporate lawyers if they think you're portraying them negatively. I am not a lawyer (nor a writer or publisher of fiction), but my impression as a reader is that minor men...
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...
For internal documentation I've found wikis to be quite useful. A wiki has several useful features for this task: built-in change-tracking doc can be structured as several pages (e.g. one per ma...
This XKCD strip shows a visualization approach for tracking character interactions -- who's with whom when. It works pretty well even with a complex plot with many characters (one of the examples ...
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...
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...
As we've seen on earth, communities count time in reference to key events -- the creation of the world, the birth of a new religious figure, the beginning of a king's reign (these ones have less st...
This depends in part on how recognizable the landmark is to readers. On the one hand, if your scene is set in Times Square, it's hard to change anything -- enough people know the place that if you...
Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what...
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 ...
Would it count as "previously published" if it appeared in your (print) newspaper, but it was three years ago and nobody is likely to still have old copies lying around? This seems like an analogo...
If you are one of those rare people who can write, straight through, without any major refactorings or changes of direction along the way, more power to you. But for many people, and IMO any long-...
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...
Consider something like the following: ... has only been thoroughly evaluated by a small number of experts in the xx literature, the most significant of which are (author1992, author1994, ...)....
Both phrasings refer to an action that occurred in the past (his going). The additional nuance you need to consider here is whether the question itself sounds like it occurred in the past. A ques...
I've seen this done with a "watermark" that says (usually) "sample data" (kind of like this, from here, though that's a table rather than a chart). Think of the "draft" watermark you sometimes see...
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 ...
For what you need to do legally, you'll need to consult a lawyer in your jurisdiction. Laws vary. The rest of this answer is about practical considerations. First, are you on good terms with the...
Ah, the "you can write in one context, so you must be an expert in writing in another context" fallacy. I've been on the receiving end of that too. Being a good academic writer, or engineering wr...
