Activity for Monica Cellio
| Type | On... | Excerpt | Status | Date |
|---|---|---|---|---|
| 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) |
— | over 10 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) |
— | over 10 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) |
— | over 10 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) |
— | over 10 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) |
— | over 10 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) |
— | over 10 years ago |
| Answer | — |
A: How can I prevent, or work around, unfortunate hyphenation in critical words? With help from a coworker I was able to fix this by adding the following to the FO stylesheet: And likewise for other elements that should get this treatment, like `methodname` and `literal`. This creates a wrapper around the native style, changing hyphenation only... (more) |
— | over 10 years ago |
| Question | — |
How can I prevent, or work around, unfortunate hyphenation in critical words? In technical documentation, sometimes the tool's automatic hyphenation makes a bad break in the middle of a term, like the name of an environment variable or function. In these cases I would rather have a short line than hyphenation, though I want hyphenation in the document in general. I can try to ... (more) |
— | over 10 years ago |
| Answer | — |
A: becoming better blogger when I write about diverse topics In my experience there are two main types of blogs out there, topic-focused and person-focused. You're describing the latter. Person-focused blogs, which cover a range of topics and styles with the unifying theme of "interesting enough for the blog author to want to write about", seem to attract a s... (more) |
— | over 10 years ago |
| Answer | — |
A: Really Stuck: Writing Dialogue If your antagonist is living in the present time (but is 1000 years old), then is there any reason to believe that his speech hasn't evolved? Think about what happens to people when they move to a new place with language patterns different from the ones they grew up with; don't they tend to adapt? T... (more) |
— | over 10 years ago |
| Answer | — |
A: Punctuating Thoughts "Hard and fast rules" come from the style guide you're following; all else is convention. I've seen both styles in fiction, so to decide which to use you can look at examples of similar type (genre, length, etc) to see what they do. If you're submitting for publication, then the publisher might have... (more) |
— | over 10 years ago |
| Answer | — |
A: Background speech with foreground dialogue I saw an effective example of this in 1634: The Baltic War (David Weber & Eric Flint) recently. The factors that made it work were: - The background speech was in italics (as you've done here). - The passages of background speech began and ended in the middle of sentences. - There wasn't a lot of ... (more) |
— | over 10 years ago |
| Answer | — |
A: Describing common hand gestures In many cases you don't actually need, or necessarily want, to describe the gesture itself. It is often enough, or even preferable, to (a) convey that there was a gesture and (b) convey its meaning, without describing the gesture. There are at least two reasons for this: 1. The gesture is idiomatic ... (more) |
— | over 10 years ago |
| Question | — |
API reference doc: best practices for describing opaque parameters? The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool is Javadoc. One property of such generated documentation is that the code interfaces -- for example,... (more) |
— | almost 11 years ago |
| Answer | — |
A: Publishing price comparisons. Is it allowed? Buying guides, including reviews and prices, are not uncommon, with the quintessential example (at least in the US) being Consumer Reports, a monthly product-review magazine (with web site). Local laws may vary, of course. Since this is a "small localised list", perhaps there is a matter of etiquett... (more) |
— | almost 11 years ago |
| Answer | — |
A: Does the following piece have too much dry narration (mundane tasks, moving about)? I don't think the information is entirely unnecessary, but it's dry. Lauren gave a good answer about adding more feeling; in this answer I'll focus on another style issue. You have a lot of "she did this, then she did that, then she did something else...". That feels repetitive. Sometimes you want t... (more) |
— | almost 11 years ago |
| Answer | — |
A: In end user documentation, should screenshots come before or after the text that references them? If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through secti... (more) |
— | almost 11 years ago |
| Answer | — |
A: How specific should I be when outlining the plot? It's tempting to include all this information that you already know, so what's the harm? The harm, as you indicate in your question, is that the outline no longer serves as a good gauge of your progress through the work. What is the purpose of the outline? If your publisher requires it then follow y... (more) |
— | almost 11 years ago |
| Answer | — |
A: How to represent dependencies in outlines As Lauren said, the outline is a tool for your use, not a deliverable in its own right, so if you deviate from it, that's ok. You asked how to track these dependencies in an outline. A technique I have used is to diagram my outline, using arrows to point from an entry to each one that it depends on.... (more) |
— | almost 11 years ago |
| Answer | — |
A: Should the transition sentence be placed in the end of the current section, or at the beginning of next section? It depends on the context. In the example in this question, cars are being presented as connected to buses somehow, so it makes sense to have this kind of segue. However, in a chapter with a bunch of stand-alone sections, it doesn't. If the same chapter is talking about buses, cars, trains, planes, ... (more) |
— | almost 11 years ago |
| Answer | — |
A: Avoid blending Fantasy and Sci Fi Why does apparent technology have to actually be technology? Can't it be either mundane or magical instead, even if in our world we would call it science or tech? Strength and speed can be enhanced through medicine (and its cousin, magical potions). Hoverboards with mechanical motors/propellors/jet-... (more) |
— | almost 11 years ago |
| Answer | — |
A: How to better describe "jet-black (pitch-black) darkness"? Instead of a looking for a single expression, consider the cases individually. If you can show us that it's black (pitch- or otherwise), you won't need to tell us. Consider: > Pine resin cloaked the dense forest in darkness... > > I also recalled one moonless 1 night Sometimes you really do just n... (more) |
— | almost 11 years ago |
| Answer | — |
A: What is the best way to learn technical writing? My background: wanted to be a programmer, entered a math program in college (because that was how you got to CS), loved the CS but hated the math, switched to technical writing and took the CS from there, and ended up doing a mix of programming, tech writing, and software design for the next (cough) ... (more) |
— | almost 11 years ago |
| Answer | — |
A: What do you do if you enjoy writing, but have no ideas? Do you read? Study anything? Noodle around with puzzles or technical problems (in any field)? If so, try reacting to that. Write about something you've just learned and what further thoughts and questions it prompts. Write about something you've just read -- not necessarily a review, but perhaps the... (more) |
— | almost 11 years ago |
| Answer | — |
A: Chopped sentences with too many conjunction, and repeating the subject again and again For a screenplay, it is probably more important to be clear than to have excellent, flowing prose. (I'm not a screenwriter.) For the more-general case of descriptive prose, however, one approach is to convert "they are" verbal clauses to adjectival clauses. Instead of: > Hundreds of people are stand... (more) |
— | almost 11 years ago |
| Answer | — |
A: Ways to improve your writing skills In addition to reading (as suggested by others), practice writing in contexts that are already available to you. (Starting a blog is good too, but if you can't build a reader base that can be discouraging.) You're a CS major; that presumably means you are designing and implementing software. There is... (more) |
— | about 11 years ago |
| Answer | — |
A: How should I introduce new and complex technologies or tools? Lauren's and SF's answers give good advice for dealing with the necessary explanation. My additional advice is: make sure it's really necessary. Driving a car is a pretty complex task (ask anyone who's taught a teenager :-) ), and there are cases where it might be important to describe in detail the... (more) |
— | about 11 years ago |
| Answer | — |
A: How can I consistently distinguish among tables, fields, and records in a database? Does the publication in question have relevant style guidelines? (I'm assuming not or you wouldn't be asking here.) In your proposed solution, you are using both formatting and (initial) explicit labeling to convey information: "the trees table" rather than just " trees", for instance. This is good;... (more) |
— | about 11 years ago |
| Answer | — |
A: Getting details of a past century right Historical re-enactors share your problem. Here are some of the things we do: - Read history books, sure, but sometimes it's the museum catalogs that show everything from art to architecture to everyday kitchenware that really help. Then ask yourself what it would be like to live in a building li... (more) |
— | about 11 years ago |
| Answer | — |
A: How should we go from Stack Exchange Q/A to publishable PDF with the least hassle? We have learned through experimentation that a new-enough version of Microsoft Word (we tested with 2010) supports format-preserving cut-and-paste from Stack Exchange posts. We drew up some formatting guidelines to get the content into shape (e.g. de-linkifying, since this is for paper). This still i... (more) |
— | about 11 years ago |
| Question | — |
How should we go from Stack Exchange Q/A to publishable PDF with the least hassle? Over on another site we're talking about taking some of our content (on a particular theme) and re-packaging it as a printable PDF. (The primary use case is paper.) This wouldn't be a straight dump of the original posts; sometimes you want to edit some for a different audience, links don't work, and ... (more) |
— | about 11 years ago |
| Answer | — |
A: Is there any standardized definition of a "Mary Sue"? A "Mary Sue" is a character who represents a highly-idealized version of the author (usually). This is the sort of character who, as needed, can perform brain surgery with one hand on a turbulent jet that she's piloting absent-mindedly while working on a cure for cancer -- that sort of thing. Wikiped... (more) |
— | about 11 years ago |
| Answer | — |
A: How can I express this fragment more clearly and concisely? Try something like this: > This application is for users of (ESP) who need to understand its results quickly and easily. (Product) takes the metrics compiled by (ESP) and presents them in a way that makes troubleshooting and documentation easier. (Product) produces reports for (business function A),... (more) |
— | about 11 years ago |
| Question | — |
What is the role of editors in news media today? Back when rocks were soft and the world wide web hadn't yet been invented, I worked on a college newspaper that, I was told, followed the same patterns as professional papers. (That is, the skills we learned doing this would transfer.) Between the journalist's story submission and the print copy stoo... (more) |
— | about 11 years ago |
| Answer | — |
A: How do I approach writing an autobiography? Unless you are near (what you think is) the end of your life, you don't have enough data yet to know what will ultimately be the best organization. So don't try to create an outline; just start writing pieces. Chronological seems logical but might not be very engaging. Is reading a day-by-day (or we... (more) |
— | over 11 years ago |
| Answer | — |
A: Writing a programming book: how to present directory structures I do something similar to your ASCII implementation, but instead of an ASCII block I use compact bulleted lists (with sub-lists). File/directory names are still styled as they would be in running text. In addition to conveying the structure, this also gives me a handy place to add explanations where ... (more) |
— | almost 12 years ago |
| Answer | — |
A: How well would this beginning sell the book to readers? Not necessarily for money The ideas in this excerpt grab me. We have a first-person narrator who's dead; how does that work? This seems to have involved some sort of deal to help the narrator's son, and there seem to be alternate timelines or worlds involved. This makes me curious and it does not feel too information-intensiv... (more) |
— | almost 12 years ago |
| Answer | — |
A: How can you write less to say more? My experience is in software documentation (particularly programming interfaces), so I'll answer from that perspective. I think these principles are pretty general, but I've never written manuals for, say, airplane repair. Generally, you want your documentation to say all and only what is needed for... (more) |
— | almost 12 years ago |
| Answer | — |
A: Should I put colons with second-level titles? First off, if you're writing for the government they might have a format they expect, so if so and it says something on this point, it wins. Otherwise, I would not use colons in any of your titles or paragraphs. The colon's job is to introduce what follows (e.g. in a list), but a title/subtitle/subs... (more) |
— | about 12 years ago |
| Answer | — |
A: Is it overkill to follow style-guides for technical writing? For documentation that will be published outside your organization, it is usually important to follow a style guide (pretty much any one) so that all the documentation reads with one "voice" even though it was written by a bunch of different people. As noted by Lauren Ipsum, you don't read the style ... (more) |
— | about 12 years ago |
| Answer | — |
A: Where to find authors for highly technical articles? One resource is Techwr-l, a large, long-running mailing list and web forum. You can't just post job ads to the mailing list, but they accept ads/sponsorships. I've never advertised there so I don't know how well it works, but you could ask them about success rates. You could also look into the Socie... (more) |
— | about 12 years ago |
| Answer | — |
A: Avoiding "and" as a sentence structure You have six sentences' worth of text in three conjoined sentences. Not all of the pairings are necessary and some might not be "correct"; for example, you could just as easily conjoin the question and the answer, which are currently part of two different sentences. One way to attack this problem is... (more) |
— | about 12 years ago |
| Answer | — |
A: How to write a book for a given reading level? One approach would be to record your story-telling sessions, particularly in a way that captures his reactions. You could then review those recordings to see what worked and what didn't (e.g. you had to repeat something in a different way). Reading comprehension is different from aural comprehension,... (more) |
— | about 12 years ago |
| Answer | — |
A: How can I make a collection of essays / arguments more attractive to publishers? The up-hill battle you face is that there's a lot of material out there and publishers can afford to be choosy. Based on observation only (I haven't tried to get essay collections published nor am I a publisher, but I've watched others pursue this), publishers are looking for a unifying theme that ca... (more) |
— | about 12 years ago |
| Answer | — |
A: Habits and routines for my first tech writing job I'm answering this as a technical writer but I don't have translation experience so can't address any aspects specific to that. Many of the habits that (I hope) you already have as a software developer apply equally to technical writing: - Design first: figure out how you will structure the documen... (more) |
— | about 12 years ago |
| Answer | — |
A: Explaining that experience is far greater than official job title implies I agree with Lauren Ipsum's answer. Some additional points: The paragraph you posted for the cover letter talks about what you want to do, but you've actually done this. Call that out; lots of people have aspirations, but you've got solid experience. Consider working in something like the following:... (more) |
— | about 12 years ago |
| Answer | — |
A: Slow openings: What is it about this Neil Gaiman opening that pulls the reader in? I think it's three things. First, the accessible writing style, with its informal language that matches how regular people think and talk, is helpful but not sufficient. Second, the character's acceptance of the situation, which he appears to have accepted from the beginning, is unusual; we expect co... (more) |
— | about 12 years ago |
| Question | — |
Best practices for maintaining documented code examples? 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 showing only the relevant excerpts from the sample code. (Nobody wants to see a 200-line program inline ... (more) |
— | about 12 years ago |
| Question | — |
How do you build good per-book *and* global indexes? For our SDK, we generate individual documents (PDFs) and one big HTML doc set (CHM file) from the same Docbook source. Each book has an index, and the HTML version has an integrated index that is the union of all the individual entries. We have been focusing on the individual books in crafting our i... (more) |
— | about 12 years ago |
| Answer | — |
A: What marketing techniques are effective for short story eBook collections? The challenge with publishing these days, especially with the great supply of e-books, is getting people to look at your stuff among all the competition. There's so much to choose from; if I've never heard of you, what will get me to buy? Short stories seem to this consumer to have a big advantage: y... (more) |
— | about 12 years ago |