Activity for Monica Cellio
| Type | On... | Excerpt | Status | Date |
|---|---|---|---|---|
| Answer | — |
A: Using real words from a foreign culture feels like 'Calling a rabbit a "smeerp"' I've found that the main key to unfamiliar words -- and this applies to jargon in technical writing as much as it does to foreign or made-up words in fiction -- is density. The example in the XKCD comic is irritating because it can't get through a single sentence without three new words. The situatio... (more) |
— | almost 6 years ago |
| Answer | — |
A: Citing an unknown primary source? Only cite sources you've actually seen. In this case, it sounds like you have a secondary source (your link) that quotes from and does not cite a primary source. All you can say with certainty is that this secondary source says that primary source says what it does. The way you handle this in your d... (more) |
— | almost 6 years ago |
| Answer | — |
A: How can show that my cold hearted character is coping with grief? The heartlessness you describe is "externally facing" -- the actions he takes and the way he interacts with others. That doesn't mean there's no heart at all in there; it just means he doesn't allow it to influence his actions. You can show signs of Bob mourning in his thoughts (if the story is firs... (more) |
— | about 6 years ago |
| Answer | — |
A: How can I get a technical writing job for software apps without a degree? In many (most?) companies you do not need a degree or certificate; what you need is demonstrated skill. Technical writing is not a super-common degree to begin with; many technical writers have degrees in English or computer science or other fields. I had a writer on my team once whose degree was in ... (more) |
— | about 6 years ago |
| Answer | — |
A: Can I include a short biography of the person to whom my book is dedicated? It sounds like you want to introduce your readers to one of your inspirations (since you said this person is connected to one of the characters in your book). This is sometimes done in a preface, as opposed to in the backmatter, and can help "set the stage" for the work that follows. An author's pref... (more) |
— | over 6 years ago |
| Answer | — |
A: How to construct a technical tutorial when the user can't verify the results after each step? In addition to grouping steps that must be done together and teaching troubleshooting, give the user a way to recover -- because sometimes the user isn't going to figure it out and is going to bail on you if there's no path forward. If your tutorial is broken up into units, provide a correct answer ... (more) |
— | over 6 years ago |
| Answer | — |
A: 'for example' and 'e.g.' in a thesis "E.g." is an abbreviation for the Latin "exempli gratia", which means "for example". The abbreviation is fairly common in "advanced" writing, like theses, in my experience. However, it's an other-language abbreviation, so it's a small hurdle for some. Might your thesis have readers who are less adva... (more) |
— | over 6 years ago |
| Answer | — |
A: Rewriting User Guides as Stories As noted in this answer, you do need to be mindful that for a user guide your reader's goal is information, while for a rulebook it can also be entertainment. If the entertainment gets in the way of the information, the reader who has to finish his task today and is stuck on how to do the next step i... (more) |
— | over 6 years ago |
| Answer | — |
A: How can I distance myself from an article published under my name, with edits I disagree with? I was the editor of my university paper back in the day. Chris Sunami's answer is right; university newspapers are produced by amateurs, people learning the trade (who might not even be taking journalism-related coursework), and they sometimes err. In addition to following the very good advice from C... (more) |
— | over 6 years ago |
| Answer | — |
A: Where do I start with C++ documentation? What you write depends on your audience. API reference documentation -- the output of tool- like Doxygen -- is usually for the users of that API. Such externally-facing documentation focuses on the contracts of the API and how its various components fit together -- how are you supposed to use this co... (more) |
— | over 6 years ago |
| Answer | — |
A: Is it okay to write a story where the protagonist is a Terrorist? One man's terrorist is another man's freedom fighter. In other words, your main character probably doesn't see himself as a terrorist, so a first-person or close third-person story focusing on that character can present something more nuanced than "terrorist, ick". I've read stories where I know the ... (more) |
— | over 6 years ago |
| Answer | — |
A: Should creativity or eloquence in a technical document be removed during review? This is a supplement to this answer. Readers, especially technical readers, notice small variations and especially inconsistencies. If you talk about "removing" a resource in one place and "deleting" it in another, some but not all readers will think that's two different operations. This problem is ... (more) |
— | over 6 years ago |
| Answer | — |
A: Using colloquialisms the reader may not be familiar with Dialect used in dialogue can work well, especially when the writer is fluent. (Writers who aren't fluent in the dialect they're trying to use can make a mess of it.) Dialect is another aspect of how your characters speak. If you do it in a way that the meaning is either clear or supplied by context, ... (more) |
— | over 6 years ago |
| Answer | — |
A: Verb tense for technical document titles The Microsoft Style Guide says it depends on usage: > In general, use imperative constructions in conceptual or informational topics for both the title and the headings. Describe what the user wants to do in the user’s language. > > For material that does not describe a task, use a noun phrase, not... (more) |
— | over 6 years ago |
| Answer | — |
A: What are the benefits of including complete working code samples in documentation There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes too simple (simplistic), but this example sh... (more) |
— | over 6 years ago |
| Answer | — |
A: How to effectively document a product composed of complex microservices? I've worked on a few doc sets like that. While API reference documentation is one case where you see this problem, the problem occurs at the "module" level too. Your question is about microservices, which take inputs and produce outputs and can be chained together. I'm going to describe a case that ... (more) |
— | over 6 years ago |
| Answer | — |
A: Should software product release notes be in marketing voice or technical voice? (software documentation) Release notes should describe what changed as seen by the users. That doesn't necessarily mean "all the gory technical details", though; as with other technical writing, you want to tell the user what he needs to know (and maybe a little more), but you don't want to overwhelm him with unneeded detail... (more) |
— | almost 7 years ago |
| Answer | — |
A: How do I write a report analyzing a system's weaknesses and how to address them? I've done this sort of thing as part of evaluating technologies. It's usually cast as an evaluation, covering both benefits and weaknesses, rather than just weaknesses. I suggest getting clarification on whether to address benefits too. The purpose of such a document is to help people make informe... (more) |
— | almost 7 years ago |
| Answer | — |
A: How to write about transgender issues while avoiding cognitive dissonance? As this answer points out, name changes aren't limited to transgender people. A practice I've seen often is to include both names when clarification is necessary. For example, I'd adjust the example in your question as follows: > Caitlyn Jenner (then Bruce Jenner) won the gold medal in the men's dec... (more) |
— | almost 7 years ago |
| Answer | — |
A: What's the least distracting method to inform editors I'm a woman? I once saw someone in your situation address the problem by adding a (gendered) middle name to signatures. This could either be your real middle name if you have one, or a nickname that you're prepared to answer to. If it's your real name, just write it normally: > Morgan Ann Meredith If it's a ni... (more) |
— | almost 7 years ago |
| Answer | — |
A: What constitutes a co-author credit? In many books you'll see an author's note at the beginning (or sometimes end) in which the author thanks various people for their help -- beta readers, members of a writing circle, editors, advisors on particular subjects (historical periods, military protocol, xenobiology, whatever), family members ... (more) |
— | almost 7 years ago |
| Question | — |
How can we make reviewing HTML documentation easier? Summary: I'm looking for a way for reviewers to comment collaboratively as close to "inline" as possible on a large HTML project. The problem in detail I work on a team that documents a large product. The HTML documentation set has hundreds of individual pages (with sidebar hierarchical table o... (more) |
— | almost 7 years ago |
| Answer | — |
A: How to handle bad source texts in technical translation? In the translation work I've seen for user-facing documentation, the translators stuck to the organization of the source but sometimes rephrased entire paragraphs, particularly if the source used idioms. This is particularly important if those translations need to be maintained over time as the sourc... (more) |
— | almost 7 years ago |
| Answer | — |
A: How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen? We solved this by adding overview files in Markdown format into the source tree and making one small configuration change. In Doxyfile, we set GENERATE\TREEVIEW to yes. This enables the sidebar table of contents, which is needed if you want these overview files to actually show up somewhere. (Normal... (more) |
— | almost 7 years ago |
| Answer | — |
A: What will be the copyright situation if I self-publish an anthology of my unpublished short stories? If you live in one of the 175 countries that are signatories to the Berne Convention, then your work is automatically copyrighted when you create it. Registration is not required to have copyright to your work. There are still advantages to registration in some countries. In the US, for example, you... (more) |
— | almost 7 years ago |
| Answer | — |
A: Single author scientific paper, 'we' or 'I'? The convention in scientific writing, at least in the hard sciences, is to avoid "I" even for single-author papers. I suspect (but can't prove) that this is why you see so much passive voice in such papers ("the doohickey was then frobitzed to induce a somethingorother reaction"). According to this ... (more) |
— | almost 7 years ago |
| Answer | — |
A: How to write a scientific journal? In your question you talk about writing "a scietific journal" (to track your progress), but then you talk about publishing in industry journals. Those are not the same thing -- and when you submit to other journals you will have to edit to meet their standards (which vary). Instead, think about the ... (more) |
— | almost 7 years ago |
| Answer | — |
A: Is Wikipedia Trustworthy? Wikipedia is a crowd-sourced site where anybody can contribute, just like this one. Wikipedia strives for verifiability and neutrality and has an active user community, but that doesn't mean that things can't get past it. It doesn't mean information there can't be wrong. Some pages are full of detail... (more) |
— | almost 7 years ago |
| Answer | — |
A: How can I establish the nature of a person/group without action? Referring to history, as noted in other answers, is a good way. You don't have to depict the action to have it come up -- in conversation, when a character reads about something online, when a detective turns up disturbing evidence, etc. You can also convey a lot by other character's reactions to th... (more) |
— | almost 7 years ago |
| Answer | — |
A: How should I start to write a flash fiction story? Flash fiction gives you very little leeway. 100 words won't allow for extended plot, character development, scene-setting... really, it's enough for one scene. I've seen people pull off more in that wordcount, but it's hard and you're a beginner. Imagine one scene that is interesting enough to write... (more) |
— | almost 7 years ago |
| Answer | — |
A: How would you cite your own figure in MLA? If the figure were in another published work, you would cite it the same way you would if it were somebody else's work. Citing yourself is done when applicable; that's not an error. You indicated in a comment, however, that you drew the figure for the purpose of the present work. In that case, you j... (more) |
— | almost 7 years ago |
| Answer | — |
A: Citing Oracle documentations of Java The general format for a reference citation in Harvard style is: > Last name, First Initial. (Year published). Title. City: Publisher, Page(s). For a web site, this guide gives the following format: > Last name, First initial (Year published). Page title. [online] Website name. Available at: URL [... (more) |
— | almost 7 years ago |
| Answer | — |
A: Do I always need to use linkers and connectors? Use transitional phrases when you need to clarify or highlight a connection. Especially in technical writing (where concise is better), don't use them just to use them. In your example, the second and third statements follow logically from the first -- you believe that data should be accessible, whi... (more) |
— | almost 7 years ago |
| Answer | — |
A: Scientific article: How to say that with our result something could be done but hasn't I don't have citations, but I've seen a couple approaches to this problem: - "One possible application of (this work) would be to..." -- by casting it speculatively like that, using "would be", you're saying "this is an idea, not something we've demonstrated". - "A possible application of (this wor... (more) |
— | about 7 years ago |
| Answer | — |
A: Indexing: after or during the writing process I've done it both ways, and have found that a hybrid approach ends up working best. Doing it at the end means you can focus just on indexing (not writing). You're more likely to be consistent in choice of terms, avoiding unintended synonyms where some entries are under term A and some are under term... (more) |
— | about 7 years ago |
| Answer | — |
A: How does one cite a print chapter in a textbook without the exact page? A general principle of citation is: only cite what you actually used. You haven't seen the original work, so don't cite it based on someone else's quote. What if the quote you're working from is wrong? Citing the original in that case would misinform people who don't know the truth or appear sloppy t... (more) |
— | about 7 years ago |
| Question | — |
In searchable documentation, what function does a glossary serve? I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google). The doc set has a glossary, which predates most team members and has accumulated a lot of entries over time. It currently contains the followi... (more) |
— | about 7 years ago |
| Answer | — |
A: How can we make compiling release notes less chaotic? I'm at a different company now than I was when I asked this question, but the new one had the release-notes problem too. Here is how we solved it (at doc's instigation): - When a bug is filed, if it's customer-reported or customer-facing, the "needs release note" box is checked. (There is a triage t... (more) |
— | over 7 years ago |
| Answer | — |
A: How to write time duration correctly I couldn't find explicit guidance in either the Chicago Manual of Style or the Microsoft Style Guide, but what I have observed (and would write naturally) is with commas: > The maximum time period allowed is 365 days, 23 hours, 59 minutes, and 59 seconds. You might be tempted to write the time in I... (more) |
— | over 7 years ago |
| Answer | — |
A: Gathering information online? In doing research, whether online or offline, there are two types of assertions you can encounter: supported and unsupported. (Just like here on Stack Exchange!) An unsupported claim isn't worth very much. Some blog post says "X", but somewhere out there is another blog post saying "not X". This hap... (more) |
— | over 7 years ago |
| Question | — |
In a formal syntax notation, how should I indicate many optional elements? We use a BNF style to convey syntax for SQL statements. For a (fictitious) example: CREATE PARSER [schema.]function [WITH [LANGUAGE='language'] [, MODE='[FENCED | UNFENCED]' [, STUFF='anotherParameter'] ]; This means that you must specify a function name (with op... (more) |
— | over 7 years ago |
| Answer | — |
A: Do you italicize fictitious television show in fiction book? I can't cite a style guide for this, only offer both observation and logic. Sanjay isn't a real person either, but you capitalized his name like you do for real people. That felt completely natural to you as a writer, right? It felt natural to me as a reader, too. Similarly, if in the context of you... (more) |
— | over 7 years ago |
| Answer | — |
A: Going from worldbuilding to writing a short story I agree with this answer that developing characters will help you to write stories (which don't have to be full-blown books). Another approach you can take is to write very short stories or even just scenes in your world. These aren't necessarily full stories (though they can be), and you might never... (more) |
— | over 7 years ago |
| Answer | — |
A: Is it strange/confusing to initiate/introduce a dialogue without a dialogue tag? The quotation marks themselves provide signal. By then tying the line of dialogue to an action in the same paragraph, it's clear that Kiyoshi is speaking. If anybody else were doing the speaking you'd need to say so, but that's not the case here. Beginning writers sometimes make the mistake of attac... (more) |
— | over 7 years ago |
| 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) |
— | over 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) |
— | over 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) |
— | over 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) |
— | over 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) |
— | almost 8 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) |
— | almost 8 years ago |