Activity for Monica Cellio‭

Type	On...	Excerpt	Status	Date
Answer	—	A: Do we use an article with every item in a list of countable singular nouns? It depends. How many of them are there? > An RLC circuit is composed of a resistor, an inductor, and a capacitor elements. This means that an RLC circuit has exactly one of each of these three elements. I crossed out your final "elements", because if you say that an X consists of an A, a B, and a C... (more)	—	almost 7 years ago
Answer	—	A: Presenting documentation for a large software product As another answer noted, landing pages are of limited utility -- you need them, but you shouldn't assume people will start there. It sounds like your modules are all inter-related, even if one customer won't necessarily use all of them. (You mentioned linking between them, for example.) So another a... (more)	—	about 7 years ago
Answer	—	A: Cite letter and article separately even though both are on the same webpage? The letter is a primary source, as you already know. This is the actual artifact, the letter the young woman received from NASA. The article about the history of these events is a secondary source; it's not a record of the events itself but a description. (It might actually be a tertiary source, but... (more)	—	about 7 years ago
Answer	—	A: Are citations the same as references in IEEE? IEEE uses a style that is common for journal articles and academic works. The citation is the full "description" of the work -- author, title, date, publication, etc. The document you linked describes the citation styles for various kinds of works and calls them "citiation standards". The reference ... (more)	—	about 7 years ago
Answer	—	A: Typographical styling of UI text in document The style I see most often in technical writing is that UI labels, like the names of menus, are bold: > From the File menu, choose Save. > > Click the Submit button. Variable text is usually italic, but this comes up more for command-line interfaces than GUIs: > git checkout -b branch-name In wr... (more)	—	over 7 years ago
Answer	—	A: How much detail when writing technical documentation? It depends on who your readers are and what they are trying to do with the information. Documentation about the same product could have very different levels/types of detail depending on whether you are writing: - Task-oriented end-user documentation, where the focus should be on how to use it, idea... (more)	—	over 7 years ago
Answer	—	A: How to present details about the setting in a fantasy world without telling? The people in your story might not know anything about Earth, but your readers do. You can show lighter gravity by describing things that couldn't happen on Earth -- a person out for a jog bounding high enough to brush tree branches, somebody casually carrying an anvil under one arm (this depends on ... (more)	—	over 7 years ago
Answer	—	A: How do I handle a backstory big enough to be a story of its own? The questions you need to answer are: 1. What story do I want to tell? 2. What elements do I need to have available to tell it? If you want to tell your backstory, and it stands alone, then you have the first book of a series, with the second book picking up some time later. This is a common appro... (more)	—	over 7 years ago
Answer	—	A: How do I decide whether to answer questions, or leave them unexplained? You don't need to -- and shouldn't try to -- explain every detail of every bit of background you've come up with. If your writing says "I had to do lots of research to write this so I'm going to make you read it", it's getting in the way of the story. However, you need to address anything that's rea... (more)	—	over 7 years ago
Answer	—	A: Why are names in fantasy novels often "original"? As others have said, most fantasy is set in a different environment, where the non-English-speaking inhabitants have different cultural and linguistic norms. So it's only natural to want to convey that. But I think there's another reason. If I name my characters "Bob" or "Pocahantus" or "Chun Li", y... (more)	—	over 7 years ago
Answer	—	A: When to introduce a list of two with the word "both" "Both" can act as emphasis when one of the two is unexpected. In this usage, the unexpected one is placed second. For example, consider the difference between: > Tom and his manager thought the customer complaint was invalid. and > Both Tom and his manager thought the customer complaint was invali... (more)	—	over 7 years ago
Answer	—	A: Can I Have My Own Website Separate of My Publisher? The nice thing about websites is that there can be more than one. Publishers, being publishers, want to promote their books, which will of course include on the web, but that doesn't mean you can't. Subject to the terms of any specific contract, and the specific promotional language/messaging they wa... (more)	—	over 7 years ago
Question	—	How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen? We use doxygen to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and we have decided to use a single tool for both. With Javadoc you can add an overview for any package by a... (more)	—	over 7 years ago
Answer	—	A: Writing a story with 10 POV characters (about a reality game show) It sounds like you're describing an ensemble cast, where there are several key characters but no single main character. While the page I linked to talks about TV/movies, the same applies to written works. The style is not at all uncommon in, at least, science-fiction novels (what I mostly read). To ... (more)	—	over 7 years ago
Question	—	Can we use MadCap Flare with semantic markup? My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions (for variables, admonitions, snippets, and so on). We use CSS to style the HTML to our tastes. We use the build tool that comes with Flare to produce th... (more)	—	over 7 years ago
Answer	—	A: How to better imply time and place changes? 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-out porch light. "Gotta remember to fix that before leaving for work tomorrow," he muttered. > > Over din... (more)	—	over 7 years ago
Answer	—	A: Where can I find a market for "offbeat" short stories about God's relationship with us? Speculative stories about God, or gods, can show up in the realm of speculative fiction, science fiction, or fantasy. Consider the following examples: - Some of the stories in Wandering Stars, ed. Jack Dann - Larry Niven's version of the Inferno trilogy - Mark Twain's Letters from the Earth - Isaac ... (more)	—	over 7 years ago
Answer	—	A: How to keep documents with example full date timeless You are concerned that a document containing a recent, past date (like from last year) will make readers think your document is out of date. One way to address that is to use dates that are obviously not recent -- Jan 1 1970, Dec 31 2037, etc. If you have a section in the frontmatter about document ... (more)	—	over 7 years ago
Answer	—	A: Can I use a phrase from song lyrics as the title of my book? Short phrases like that can't usually be copyrighted. The link is from the US government, but I believe it to be the same for most of the Berne Convention countries. Of course you should consult your local law on this. In this specific case, there's already a TV show by that name), so they apparentl... (more)	—	almost 8 years ago
Answer	—	A: Starting a sentence with the name of a program or command-line tool: capitalization? Rule #1 in technical documentation is: don't mislead the reader. If the command or function name begins with a lowercase letter, capitalizing it is an error -- it's not "Cat" but "cat". The Microsoft Manual of Style specifies that literal elements like this should be written with their correct case. ... (more)	—	almost 8 years ago
Answer	—	A: How do I announce an area-restricted feature without discouraging the rest of my visitors? You can cast it as an early report on your beta launch, or as a preview of your forthcoming launch. Assuming that you're restricting it now so you can work the kinks out before spreading more widely, it helps to also talk about what you've learned -- we found and fixed this performance problem at sca... (more)	—	almost 8 years ago
Answer	—	A: How to communicate two elements of different general syntactic/semantic type in the same sentence? The problem you're having is in attaching the final clause: > NAME is...that helps...by rating...and helps... . When the reader gets to the "and" he's expecting it to bind to the "by" -- NAME helps by doing two things, rating and...helping. But the next word is "helps", which doesn't fit that patte... (more)	—	almost 8 years ago
Answer	—	A: Preserve "The Reveal" vs lying to the reader 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 this by writing these parts from the point of view of a particular character -- treat it as a speech, diary,... (more)	—	almost 8 years ago
Answer	—	A: Should I use contractions in a technical tutorial? 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 of the documentation set for expensive enterprise software, it's more common in my experience to avoid cont... (more)	—	almost 8 years ago
Answer	—	A: Adding links as foot notes 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 author, the title of the work, a publisher, and the date of publication. A URL, on the other hand, contains n... (more)	—	about 8 years ago
Answer	—	A: Is a QR card linked to the PDF of a book a good idea? 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 pretty big and some people have good eyes and can read the small page. Also, some of your readers might be usi... (more)	—	about 8 years ago
Answer	—	A: How do I show a long amount of time has passed? One way to show passage of time is by referring to time-based events. Over the course of a year you can use seasons for this; if we see your characters walking through the snow, and next see them walking through the fall leaves, we know that at least half a year has passed. For multi-year spans, look... (more)	—	about 8 years ago
Answer	—	A: Tool to batch convert DOI to citations? I haven't tested this (which would require registering with them and obtaining an ID), but CrossRef provides a web service that appears to do what you need. From the documentation: > Crossref query: > > https://doi.crossref.org/servlet/query?pid=username:password&id=10.1006/jmbi.2000.4282 > > Like... (more)	—	over 8 years ago
Answer	—	A: What word processor is recommended for writing a technical (programming) book? You haven't specified any preferences for format (source or output), and that's going to be relevant. If it's up to you, for your source I recommend a text (not binary-format) markup language -- HTML, XML, LaTeX, or similar. A text source works well with source control, works with grep/find/search, a... (more)	—	over 8 years ago
Answer	—	A: Is it acceptable to ask a question in an argumentative paper? This is a rhetorical question and, used well, can enhance the essay. The key to using this device is to first raise a question, issue, or concern that the reader might reasonably have, and then to address it. You are, essentially, putting a question in the "mouth" of your reader so that you can go on... (more)	—	over 8 years ago
Answer	—	A: How I should handle gender-neutral pronouns in technical writing? Using "he/she" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people. What I do is to write around the problem wherever possible. First off, if you're referring to the user of your API, it's better to write in secon... (more)	—	over 8 years ago
Answer	—	A: Two perspectives in a non-fiction book 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 Jumper novels by Stephen Gould; each chapter is "titled" with the name of the point-of-view character for that... (more)	—	over 8 years ago
Question	—	Maintaining readers over time with serialized fiction? I am one of several authors on a fairly new shared blog. The blog has a mix of serialized and one-shot posts. Because it's a new blog (2.5 months, 30 posts so far), there is quite a variety of posts and authors (though all on the broader theme for the blog) and we're not yet at the point where author... (more)	—	over 8 years ago
Answer	—	A: Is it necessary to explain what is written in upcoming chapters? First, if your institution has a style guide, follow its recommendations if there are any. But assuming it is silent on this point or you don't have one: It's helpful to provide an outline of the rest of the report. If you have a table of contents already that might be good enough (I've seen TRs wit... (more)	—	over 8 years ago
Answer	—	A: Should I put diagrams into a formal essay? 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 charts, and more. The main question you should be asking yourself is: does this diagram add value? Does i... (more)	—	over 8 years ago
Answer	—	A: How can I convey something without going into details? You can imply rather than say things with descriptions. For example: > He picked his way down the garbage-strewn street, stepping aside to yield to an over-sized rat. The reek of stale beer and body odor assaulted his nostrils. He averted his eyes as he passed alleys; no good could come of that. It ... (more)	—	over 8 years ago
Answer	—	A: Format keyboard keys in documents I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of ... (more)	—	over 8 years ago
Answer	—	A: How long is too long for a blog post? A longer post can work on a blog that usually tends toward shorter posts if you take some care in structuring it. "Here are 20,000 words, plus equations" may send some people to the "back" button right off, but a five-minute introduction followed by an expansion can satisfy both audiences -- those lo... (more)	—	over 8 years ago
Answer	—	A: How to cite nonpersonal email "Private" doesn't mean just one recipient; it just means "not public". When you throw a by-invitation party in your home it's a private affair even if there are 50 people there. Email is the same way. The bigger problem here is that the person you're citing didn't write directly to you. So if you ci... (more)	—	over 8 years ago
Answer	—	A: How to work on a new software feature that affects different topics 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. However, if Y is a corner case or involves a lot of changes to several other features, you might be better ... (more)	—	over 8 years ago
Answer	—	A: How do I get rid of the tic of paired adjectives, predicates, etc.? When I'm editing technical documentation (and, ideally, when I'm writing it in the first place), I try to make every word earn its place. If both words in your phrases need to be there to make your point, then don't worry about it -- that's not a tic but the writing process. In the case of pairs (or... (more)	—	over 8 years ago
Answer	—	A: What do I put on my copyright page when self-publishing? If you're self-publishing and not doing it through a company, use your real name: "Copyright (C) 2015 John Doe". Under the Berne Convention (which applies in most countries), you own the copyright from the moment of creation until you assign it away. You have no need to assign it away, so you don't n... (more)	—	almost 9 years ago
Answer	—	A: When Dialogue is used for more than one character? No. All that is required is that the reader know who is speaking. The conventions of dialogue do a good job of that. > Bob continued, "blah blah blah." > > "But wait", Sue asked, "what about blah blah blah?" > > "Blah!" > > "Blah?" > > He growled, "no, blah!" And so on. Each change of speaker ... (more)	—	almost 9 years ago
Answer	—	A: Which citation style do I use if I'm writing a religious book? Consider how your reader will use the book. In an academic work (which this is not), readers: - are likely to already be familiar with the cited works (they're also researchers in this field, after all) - will rely on the works you cite to evaluate your work (they care about those citations) - re... (more)	—	almost 9 years ago
Answer	—	A: I have three dead-end chapters. Should I keep them or remove them? While there might be a payoff coming in the fourth chapter, if readers get frustrated enough on the way there, some of them will bail and never finish your book. So while you can ask your reviewers to forge ahead and read the rest, you can't assume readers will. Consider one of the following two app... (more)	—	almost 9 years ago
Answer	—	A: How could collaborative writing in one world work? A supplement to this answer: All the shared-world anthologies I've read had "framing" stories written by the primary author, the one who came up with most of the setting and is driving the process. For example, Eric Flint wrote or co-wrote several of the 1632 novels, including the first one, and Rob... (more)	—	almost 9 years ago
Answer	—	A: How to create a functional document for in-house reference? In many ways you approach this the same way you would approach any other new project: - Review any available high-level descriptions (like functional specifications) and user stories: what is this thing and how are people meant to use it? - Identify your key contact (if you don't have one, ask your... (more)	—	about 9 years ago
Answer	—	A: Technical writer degree with an English BA? Why not test the hypothesis, starting with the negative test? You are unhappy in your current career. You have some background but nothing official. A BA in English might or might not be a meaningful credential (in my experience it depends on the school and the program's focus -- literature is proba... (more)	—	about 9 years ago
Answer	—	A: Ethics of incorporating a supplier's technical documentation into one's own documentation? I am not a lawyer and this is not legal advice. First, check any license terms that accompany Company S's documentation. They might have published it with the intention that other vendors will incorporate it (e.g. some Apache platforms), or they might not intend that but allow it under their license... (more)	—	about 9 years ago
Answer	—	A: Who do I cite as my source? You cite the (or a) source that you used. If you read it in Book A and that book says it came from Book B, you cite Book A because that's your source. If you choose to follow the reference and see it in Book B yourself, then you could cite either A or B (you used both). In that kind of situation, it'... (more)	—	about 9 years ago

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