Activity for Monica Cellio‭

Type	On...	Excerpt	Status	Date
Answer	—	A: What's the common practice for warranty chapters in technical manuals? This is a decision you need to make in consultation with your company's legal advisors. The ability to defend against claims is affected by both what the warranty says and how prominent it is. A separate document or appendix that people are less likely to read might cause problems in this area. (Neve... (more)	—	about 9 years ago
Answer	—	A: Using a foreign language that uses a different written alphabet Rules? No, not beyond any that your publisher or editor might have. But one factor to consider is that, assuming you're not publishing in a specialized or foreign market, your readers probably won't know how to pronounce the words in a different alphabet -- you can't sound things out if you don't kno... (more)	—	about 9 years ago
Answer	—	A: Any Good Method for Calculating Word Count Based on An Outline? Outlines vary in how much text they cover; some people might write a multi-page outline for the same content for which another would write: > Boy meets girl. > Boy loses girl. > Boy goes to mad-scientist school and builds a new girl. So the only way to know how your outlines map to word count i... (more)	—	about 9 years ago
Answer	—	A: How do you effectively denote a non-"heading-ed" transition into a concluding section? This is almost never done in my experience (which is mostly with technical documentation and some journal articles), for the reason implicit in your question: it's confusing. Once you start carving off sub-sections, the expectation is that each such subsection runs until the next division or the end ... (more)	—	about 9 years ago
Answer	—	A: In what order should I describe a setting? I largely agree with this answer, to which I add: 1. Order of perception by your POV character fits nicely into all the other stuff that you're telling through that POV, so it's a good place to start. 2. On rare, special occasions, you can get extra impact by violating that: > The cool breeze thro... (more)	—	about 9 years ago
Answer	—	A: Is Blogging considered a form of creative writing? 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 of the term. There is plenty of creative writing that follows the rules and conventions of its language, ... (more)	—	about 9 years ago
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)	—	about 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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)	—	over 9 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 9 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 9 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)	—	almost 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)	—	almost 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)	—	almost 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)	—	almost 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)	—	almost 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)	—	almost 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 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)	—	about 10 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)	—	over 10 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)	—	over 10 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)	—	over 10 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)	—	over 10 years ago

• ← Previous
• 1
• 2
• 3
• 4
• 5
• 6
• 7
• Next →