Activity for Monica Cellio
| Type | On... | Excerpt | Status | Date |
|---|---|---|---|---|
| Answer | — |
A: Any advice on how to learn DITA for technical writing? I don't know how much benefit you'll get on a resume from having read about, as opposed to used, DITA, but some knowledge is better than none. DITA is both a specific framework and an approach. My documentation group is currently working through the book DITA Best Practices: A Roadmap for Writing, E... (more) |
— | almost 10 years ago |
| Answer | — |
A: "That's when" vs "That was when." From a strictly grammatical point Lauren's answer is right -- you're talking about something that happened in the past, so "that was" is correct. However, dialogue is often more colloquial and a first-person narrative can be more like dialogue than strict narrative. If you're trying to evoke the fee... (more) |
— | almost 10 years ago |
| Answer | — |
A: Use of realism in a fictional setting Realism has several components. Different ones dominate in different genres/settings and among individual readers. - (Real) setting accuracy: If you're describing a real place or a time in history, people who know something about that will respond based on how closely you match what they know. If th... (more) |
— | almost 10 years ago |
| Answer | — |
A: Editing: Those darn comma splices That's not a comma splice; that's a statement followed by an elaboration.1 The second does not stand alone, so a semicolon there would be incorrect. This would be a comma splice: > It had been a thousand years since the Razzies had known the horrors of the king's might, it was a thousand years sinc... (more) |
— | almost 10 years ago |
| Answer | — |
A: How do I explain a lack of sufficient data in my essay? 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. There are two basic approaches: - Only write about things you can back up. For example, Consumer Repo... (more) |
— | almost 10 years ago |
| Answer | — |
A: Should embedded figures/images be placed before or after they are referred to in text? This depends in part on the type of writing (technical reference manual? novel with illustrations? etc) and how people will read it (printed book? online?). If a reader follows a reasonable path1 through the document, there should never be a point where he's looking at something incomprehensible. Th... (more) |
— | almost 10 years ago |
| Answer | — |
A: What Self Publishing Company should I contact? You don't need a publishing house for that (and anyway your intended distribution is too low for such companies to be interested). You just want to self-publish your work. When I self-published a book (making, ultimately, about 300 copies), I went to a commercial duplication place that could do prod... (more) |
— | almost 10 years ago |
| Answer | — |
A: Using species from another novel, in my novel, copyright infringment? 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 overused; Tolkien used them well so his works are the benchmarks against which others are often measured, but he ... (more) |
— | almost 10 years ago |
| Answer | — |
A: What is the average cost of software for DITA authoring? DITA is an XML format, so any editor or IDE that supports XML will work for you. Options with good XML support range from Eclipse (free) to Oxygen and Epic (several hundred dollars per seat). Of course, anybody who's comfortable getting up close and personal with the XML can use Emacs, vim, or Notepa... (more) |
— | almost 10 years ago |
| Answer | — |
A: How can I turn my short story into a novel? 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. Your short story is already a self-contained unit; what else is going on around those characters, in tha... (more) |
— | almost 10 years ago |
| Answer | — |
A: Is it necessary to add a.m./p.m. after the time? If it's important enough to mention the hour then it's important enough to be clear which one you mean, but using "AM" and "PM" in fiction may not be the best way. If the scene already makes it clear which one is being talked about -- on the beach you talk about the sunlight dancing off the waves, fo... (more) |
— | about 10 years ago |
| Answer | — |
A: Tools for multiple creators/writers documentation without clouds 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. Locking files can be pretty limiting (especially as your group grows), but source-control systems give y... (more) |
— | about 10 years ago |
| Answer | — |
A: Why one sentence per paragraph in these news articles? There are two reasons. First, as described in this answer, news articles are written as an inverted pyramid and are designed to be cut at any paragraph break and still work. In the late stages of newspaper assembly, the editor making the decisions about what goes where and making it all fit is not go... (more) |
— | about 10 years ago |
| Answer | — |
A: Is it legal to share an index you made from someone else's book? > has anyone seen a similar situation which helps shed light on this grey area? I have in front of me two publications: Common LISP: The Language, by Guy Steele (et al.) and published by Digital Press, and Common LISP: The Index, by Rosemary Simpson and published by Coral Software Corp and Franz Inc... (more) |
— | about 10 years ago |
| Answer | — |
A: Acknowledgements in translated editions 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 but instead adding to it, even if -- for all we know -- the stuff people helped with in the first edition ... (more) |
— | about 10 years ago |
| Question | — |
In Flare, how can we make atomic change groups in review? My team uses MadCap Flare for documentation and we have an editor on the team. When a writer is ready, we assemble a review package in Flare and send it to the editor, and she makes changes and sends it back to the writer for resolution. (The writer has the final say, and responsibility for making su... (more) |
— | about 10 years ago |
| Answer | — |
A: Cheapest way to self-bind a large book When I self-published a book some years ago I had the copy shop apply comb bindings for me. At the time this cost about $1/book, but it appears that Stapes and Office Depot now charge closer to $3 for this. If your print run is small, or if you are truly willing to trade time for expense, you can bu... (more) |
— | about 10 years ago |
| Answer | — |
A: How to describe a scene involving a shift in the environment due to forbidden magic? 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 gradually notices peculiarities. Something like this: > "Sharon, no!" he shouted to no one in particular a... (more) |
— | about 10 years ago |
| Answer | — |
A: Alternate universe vs. historicity: how to set the threshold/expectations? You first described it as "set in the late 1920s", and then later said you were "writing pseudo-historically in an alternate universe". I'm not bringing this up to nit-pick your question but, rather, to point out that these are two different things. There is historical fiction, where authors try to r... (more) |
— | about 10 years ago |
| Answer | — |
A: How do I cite or give credit to a statistic on a website? 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 March 21, 2001, from http://news.ninemsn.com.au/health/story\13178.asp > > Cite in text the first few words ... (more) |
— | over 10 years ago |
| Question | — |
How should I document a database schema? 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 at what the database offers, and write their SQL queries. Think of something like SEDE. I could just... (more) |
— | over 10 years ago |
| Answer | — |
A: How do I approach rewriting an entire user guide in an agile environment? 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 vast majority of the content anyway, so better to think of it as a new book (for which you might be able... (more) |
— | over 10 years ago |
| Answer | — |
A: Is there a standard for what should be included in an index? 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 novices or some of each? An index's primary job is to have an answer when somebody comes to it with a questio... (more) |
— | over 10 years ago |
| Answer | — |
A: Pros and cons of using real brand/company names? 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 mentions don't provoke their wrath but if your plot hinges on, say, a horribly-malfunctioning vehicle, you m... (more) |
— | over 10 years ago |
| Answer | — |
A: Choosing between your Mother Tongue and another language 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 published work, by native speakers that doesn't really measure up. English is a difficult language full of... (more) |
— | over 10 years ago |
| Answer | — |
A: Best Tool to Create User Guides 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 major section) for easier management; individual pages can then be edited without any need to merge chan... (more) |
— | over 10 years ago |
| Answer | — |
A: How do you visualize plot structure? 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 is Lord of the Rings). While I haven't tried this myself, in your shoes I would try a similar approach, ... (more) |
— | over 10 years ago |
| Answer | — |
A: How does one avoid incomplete changes to documentation? 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 risk here. In my experience you can do some things to address the problem when it happens, and some things... (more) |
— | over 10 years ago |
| Answer | — |
A: How to reference a figure from text in a technical document 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 consistent with "Table", which I haven't seen abbreviated as "Tab.".) Whatever you do, be consistent -- refer to a... (more) |
— | over 10 years ago |
| Answer | — |
A: Stardate(Julian Day) - Problem 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 staying power), and so on. When calendar systems encounter each other (I say the year is 5774; you say it'... (more) |
— | over 10 years ago |
| Answer | — |
A: I need advice regarding the use of real-world locations in a novel 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 do, it'll just draw attention to your changes (which may be distracting). On the other hand, if your sce... (more) |
— | over 10 years ago |
| Answer | — |
A: How can I write better code-based reference documentation for programming interfaces? 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 corresponding tools for other languages. (I've seen this kind of documentation for C++, C#, and JavaScript APIs.) T... (more) |
— | over 10 years ago |
| Question | — |
How can I write better code-based reference documentation for programming interfaces? 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 arguments it takes, and software turns those comments and the signatures from the code into reference do... (more) |
— | over 10 years ago |
| Answer | — |
A: Writing an article avoiding Libel 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 things you can do to "write defensively", so to speak. Following are some things I was taught in college ... (more) |
— | over 10 years ago |
| Answer | — |
A: Published on blog but taken down: Still remains previously-published? 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 analogous case. Your blog post, if it was at any time public, probably is still out there, in the Wayback Machi... (more) |
— | over 10 years ago |
| Answer | — |
A: What is the purpose of version control? 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-running project, source control is a major benefit. Here are some of the reasons: - When you realize the... (more) |
— | over 10 years ago |
| Answer | — |
A: Present tense in user manuals 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 tense could be used here. Some technical writers (or style guides) make this overly passive -- "the system supp... (more) |
— | over 10 years ago |
| Answer | — |
A: How do I claim the number of scholarly articles on a niche subject is relatively small without listing every single one of those citations? 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, ...). By casting it this way you're not implying that you're listing all of them but you're also not just pic... (more) |
— | over 10 years ago |
| Answer | — |
A: "Where did X go?" vs "where had X gone." 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 question that is part of the narrative should sound like a past question, just like the other events you repor... (more) |
— | over 10 years ago |
| Answer | — |
A: Marking a chart that is not based on real data 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 on documents; same idea. Saying something in the text (or figure caption) can be helpful, but this appro... (more) |
— | almost 11 years ago |
| Question | — |
How can we make compiling release notes less chaotic? 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 bug fixes. New features are pretty easy; people know what's happening there. Our challenge is with the ... (more) |
— | almost 11 years ago |
| Answer | — |
A: What are the tool choices for producing technical documentation in PDF and web site ready HTML? 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 editor for XML files (WYSIWYG possible) - XSLTProc (with ant, but you could do make or something ... (more) |
— | almost 11 years ago |
| Answer | — |
A: Using emails in an autobiography 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 person whose email you want to use? Do you want to be on good terms after you publish your work? If so, t... (more) |
— | almost 11 years ago |
| Answer | — |
A: What is a reasonable amount of time to spend writing a product overview? 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 writer, or anything else doesn't mean you can automatically write good user-oriented material (or vice-versa... (more) |
— | almost 11 years ago |
| Answer | — |
A: How to start a technical book? 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 analysis, maybe some use-case analysis (please don't shatter my dreams :-) ), some high-level design... ... (more) |
— | almost 11 years ago |
| Answer | — |
A: Can I plug a loophole in my magic rules without rewriting the whole novel? Consequences. That something is possible within a system doesn't mean it's a good idea. You can drive your car 180MPH on public roads (if the speedometer labeling is accurate), but if you do you'll soon be getting used to a bicycle. You can subsist on nothing but Big Macs and Coke for a year, but yo... (more) |
— | almost 11 years ago |
| Answer | — |
A: Using capital letters for shouting Text in all capitals is harder to read than text in mixed case: > A 1955 study by Miles Tinker showed that “all-capital text retarded speed of reading from 9.5 to 19.0 per cent for the 5 and 10-minute time limits, and 13.9 per cent for the whole 20-minute period.” Tinker concluded that, “Obviously, ... (more) |
— | almost 11 years ago |
| Answer | — |
A: How do I write for webcomics? A comic -- web or paper, cartoon strip or sophisticated graphic novel -- is a different medium from conventional written stories. The biggest difference is that it's hard to do exposition; those long explanatory passages that you could slip into a novel don't fit into a few panels. It's also hard to ... (more) |
— | about 11 years ago |
| Question | — |
How do I avoid tech/social errors in near-future fiction? Not long ago I read a novel set in the near future (mid-21st century). My suspension of disbelief was totally fine with time travel, an implanted "universal translator" of sorts, major medical advances... but balked at plot points that depended on people being limited to land-lines (no mobile communi... (more) |
— | about 11 years ago |
| Answer | — |
A: Is my serial-killer novel horror or crime? I agree with SF and Lauren that who your POV character is affects this. But I'll take a different approach in answering this: when you talk about your project socially (e.g. with friends/family), what do you tend to focus on? What's exciting about this to you? When you're not worried about making a g... (more) |
— | about 11 years ago |