Activity for Monica Cellio
| Type | On... | Excerpt | Status | Date |
|---|---|---|---|---|
| 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) |
— | about 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) |
— | about 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) |
— | about 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) |
— | about 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) |
— | about 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) |
— | about 6 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) |
— | about 6 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) |
— | about 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | over 6 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) |
— | almost 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) |
— | almost 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) |
— | almost 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) |
— | almost 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) |
— | almost 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) |
— | almost 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) |
— | almost 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) |
— | 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 |