Notifications
Sign Up Sign In

Activity for ‭Monica Cellio‭

Type On... Excerpt Status Date
Edit Post #39319 Post edited:
we've made some improvements since my last update
1 day ago
Edit Post #5188 Post edited:
1 day ago
Edit Post #275971 Post edited:
creating the "support" tag so I can add it to the list of special tags for the tag set
28 days ago
Edit Post #275971 Post edited:
creating the "support" tag so I can add it to the list of special tags for the tag set
28 days ago
Edit Post #278005 Initial revision about 1 month ago
Answer A: Is there any benefit when writing out instructions to split it up into lots of little paragraphs, or is it better to leave it in one paragraph?
Writing in fuller paragraphs feels like it creates better reading flow, as opposed to short choppy chunks of text, but that's a prose consideration. For instructions, the primary goal is to help the reader do all the necessary steps in applicable order. If lots of steps are combined in a single par...
(more)
about 1 month ago
Edit Post #7374 Post edited:
2 months ago
Comment Post #277206 I found this to be really well-done and touching. I haven't had dogs as an adult but I grew up with pet dogs and now I have cats. I've had to make that painful decision. We had a dog who had been previously abused, though obviously we didn't get the dog's POV, just saw the effects (trust, fear, et...
(more)
2 months ago
Comment Post #277082 @aCVn `<pre>` is what we're using now (actually inside a `<div class="example">` for some other styling; don't know why). It doesn't have to be that specifically; I don't know whether this was intentional or an artifact of porting from a prior tool, but either way it was ten years ago and we can cer...
(more)
3 months ago
Comment Post #277083 I might be misunderstanding, but how does this account for the different line lengths needed on different devices? This looks like a way to style wrap, but how do you get automatic wrapping inside a pre?
(more)
3 months ago
Edit Post #277082 Post edited:
3 months ago
Edit Post #277082 Initial revision 3 months ago
Question How can we format code examples so that they work on a range of devices?
We use Madcap Flare to produce a large documentation set that contains many code examples (primarily SQL, but also C++, Java, and Python) and command-line operations. When the doc set was first planned, years ago, the people designing the layout assumed desktop browsers, as was the norm back then. ...
(more)
3 months ago
Comment Post #276843 This is excellent.
(more)
3 months ago
Comment Post #276643 Also, I'm pretty sure the "writing" tag is a data-import bug; that doesn't make sense. I've pinged the developers.
(more)
3 months ago
Comment Post #276643 I did some structuring in some of the tech-writing and tools tags. I made software a child of tools since tools is broad, and the put Word and Scriviner under software. As we come across more we can add them in.
(more)
3 months ago
Edit Post #12577 Post edited:
3 months ago
Edit Post #5330 Post edited:
3 months ago
Edit Post #26400 Post edited:
3 months ago
Edit Post #10747 Post edited:
3 months ago
Edit Post #276451 Initial revision 4 months ago
Question Hierarchical tags are now available
We just got hierarchical tags. A tag can have one or more children, and when you search on a tag you can either search just that tag or also search its children. This gives us another way to organize content. This feature was proposed on the Judaism site; you can see more background there. (Thi...
(more)
4 months ago
Comment Post #276129 @MarkBaker with the poor records we have it's hard to tell, but people also didn't used to be as mobile as they are now, so that probably led to more pressure to conform too (you're stuck with these people or, alternatively, the consequences of being expelled are severe). Plus you need something to ...
(more)
4 months ago
Edit Post #276129 Initial revision 4 months ago
Answer A: Could a 13-year-old have morality to disagree with their family's unethical business practices, while those are the norm in their society?
Setting aside your specific case, which I'm not qualified to comment on, I'll address your general question of a 13-year-old opposing family and the broader society's ethics. I have no particular expertise in history or sociology here; this is just what I've observed. Sure, this happens quite fre...
(more)
4 months ago
Edit Post #39392 Post edited 4 months ago
Edit Post #275926 Post edited 4 months ago
Edit Post #39392 Post edited 4 months ago
Edit Post #39392 Post edited 4 months ago
Edit Post #275926 Post edited 4 months ago
Edit Post #275926 Post edited 4 months ago
Edit Post #275926 Post edited 4 months ago
Edit Post #275895 Initial revision 4 months ago
Answer A: Would content at ebooks.se be in scope here?
This answer is my opinion, not moderator/admin edict. Voting and feedback in comments still apply. Their site description says the site is for publishers and readers of ebooks. Anything about publishing ebooks is on-topic here (and was on Writing.SE). Reading is probably not unless it's stuff pu...
(more)
4 months ago
Comment Post #275876 Oh, that's bold? It's a small-enough difference that, on its own, I didn't realize. Thanks.
(more)
4 months ago
Comment Post #275876 Nice! Did you mean for the first line to also be inside the blockquote? Or is it a title and not part of the poem itself?
(more)
4 months ago
Edit Post #275819 Post edited:
5 months ago
Comment Post #275819 Confirmed. It happens if you use the controls, but not if you type markdown (which is what I tried first, before realizing what you meant).
(more)
5 months ago
Comment Post #75027 @aCVn agreed on all points, including using sparingly.
(more)
5 months ago
Edit Post #75027 Initial revision 5 months ago
Answer A: Are speaker tags always necessary when multiple people are in the conversation?
Sometimes it doesn't matter who said what. In your example, where everyone has the same goals and is working together, it seems fine to leave most or all of them out -- the focus here is more on the group discussion than on individual speakers. This approach wouldn't work in cases where the speaker...
(more)
5 months ago
Comment Post #75003 Good point about burying the original content, which we need more of (and to be more findable). And we should continue to prune stuff from the original import that is not helping us -- downvotes and flags are helpful there.
(more)
5 months ago
Edit Post #74997 Initial revision 5 months ago
Question What new data should we import from SE?
When we set up this site we imported from SE as of the December data dump (the latest we had at the time). We didn't have a way to get the delta; the import code didn't use the API. We now have better data-import tools, and there's been a new data dump. We can, therefore, import stuff that was p...
(more)
5 months ago
Comment Post #74979 @aCVn agreed. The goal is to design with both in mind. In fact, most developers are using desktop, so we have to actively think about mobile -- but we want to do that *early*, not *later*.
(more)
5 months ago
Edit Post #74979 Initial revision 5 months ago
Question mice don't tap and tablet-users don't click: what word can I use for all audiences instead?
I am documenting features on a web site. The audience is end users, who could be anywhere from seasoned Internet veterans to relatively new people who came for my site's content but aren't generally online for hours every day. People visit the web site on a variety of devices, from phones (mobile s...
(more)
5 months ago
Edit Post #74968 Post edited:
5 months ago
Edit Post #7990 Post edited:
trying to fix formatting of superscripts
5 months ago
Edit Post #10769 Post edited:
I've since had the direct personal experience, so don't need this disclaimer now.
5 months ago
Edit Post #74968 Initial revision 5 months ago
Answer A: How can I make a transition from third person omniscient to first person less jarring for the reader?
Like this answer, I don't think you need to use first-person to get into a character's head. I want to focus a little more on how to do that in omniscient third-person. An omniscient narrator can get into any character's head, as you said. You want to switch to first-person, maybe to focus ("we'...
(more)
5 months ago
Comment Post #74906 @aCVn yes, it's the aggregation that makes the idea attractive to me. You can see at a glance what the overall reaction is, and if you want to read the comments you might learn more but you don't have to.
(more)
5 months ago
Comment Post #74958 Other things that can cause activity are edits and closing/reopening. But yes, there's a bug here and we're trying to characterize it. Sometimes it's right and sometimes it's not.
(more)
5 months ago
Comment Post #74906 @Mark that's an idea worth exploring. Better to not count them and then decide to (if it's compatible with how they're being used) than do it and then take it away (which could frustrate people). Once we get there at all, I could see experimenting with ways to use that data. Since it would already...
(more)
5 months ago
Edit Post #74906 Initial revision 5 months ago
Answer A: Accepted Answer?
We need to flesh this out, but the idea I have in my head, and that I recall discussing on the forum thread (which I haven't gone back and reread yet), is that in addition to votes we'll allow people to add reactions like "this worked" (and maybe a few others TBD). These would be public, unlike votes...
(more)
5 months ago
Edit Post #74875 Post edited:
5 months ago
Edit Post #74886 Initial revision 5 months ago
Answer A: Sequence of Categories
This is now configurable and I've moved Meta to the last position on this site.
(more)
5 months ago
Comment Post #74877 This is a question about the site, not about writing, so we've moved it to Meta.
(more)
5 months ago
Edit Post #74885 Initial revision 5 months ago
Answer A: Naming of Categories
"Questions" seems better than "Q&A", yes. Not everything on the site will be questions. For example, a site can have a blog or a set of resources. Some sites will have sandboxes, which are proto-questions but not questions anybody should be answering yet.
(more)
5 months ago
Edit Post #38585 Post edited:
updated link
5 months ago
Comment Post #74876 Obligatory reminder: I'm a *technical* writer; creative writing is more of a stretch for me, unlike most folks here. :-)
(more)
5 months ago
Edit Post #74876 Initial revision 5 months ago
Answer A: Writing challenge #1: The great outdoors!
She traced the delicate lines beneath the green leaf. The new growth felt fragile but tenacious, breaking free of winter's grasp, just like her. Winter? How did she know about winter? Ancestral memory, she guessed; seasons were new to her. She breathed in the scent of buds just opened into flo...
(more)
5 months ago
Comment Post #74875 Issue created: https://github.com/codidact/qpixel/issues/73 (a priority or sequence number is what I suggested too).
(more)
5 months ago
Comment Post #74875 Ooh yes, we want the sequence to be controllable somehow.
(more)
5 months ago
Edit Post #74857 Initial revision 6 months ago
Answer A: Let's restart writing challenges!
Mithical has posted the first challenge: the great outdoors! Please join us there. I hope this'll be the first of many.
(more)
6 months ago
Edit Post #74846 Initial revision 6 months ago
Question Let's restart writing challenges!
The writing challenges we've done in the past were fun and helped us flex our muscles, especially if they nudged us into new types of writing. Let's bring those back! I have created the Challenges category here. I've set the default license to CC BY-NC-SA 4.0, which in plain English means it's l...
(more)
6 months ago
Comment Post #74843 I saw a question I wanted to answer, so I imported it here the old-fashioned way. This is an experiment. I don't plan to make a habit of this or anything, but it's in keeping with the license. If I could disassociate the question I would, sorry.
(more)
6 months ago
Edit Post #74844 Post edited:
6 months ago
Edit Post #74844 Initial revision 6 months ago
Answer A: How do I deliver a historical plot reveal?
If you have placed your clues and foreshadowing well, you can present the final clues and let the reader draw the conclusion. You're aiming for an "oh wait, what? Oh wow..." reaction as the reader draws a conclusion you never spelled out. This is risky; not all readers will draw the conclusion. ...
(more)
6 months ago
Edit Post #74843 Initial revision 6 months ago
Question How do I deliver a historical plot reveal?
This question was asked elsewhere by geneaux and is copied here in accordance with the CC BY-SA 4.0 license there. Right before the climax of my SciFi novel, there's a big reveal about who the bad guys really are and how they influenced the magic system -- throughout history. This reveal will ...
(more)
6 months ago
Edit Post #39161 Post edited:
6 months ago
Edit Post #38868 Post edited:
6 months ago
Comment Post #38868 I just closed https://writing.codidact.com/questions/39190 as a duplicate of this one. There are more answers there.
(more)
6 months ago
Edit Post #39190 Question closed 6 months ago
Edit Post #39190 Post edited:
this doesn't appear to be about academic writing
6 months ago
Edit Post #74842 Initial revision 6 months ago
Answer A: Would I be able to have my characters play "Dungeons and Dragons" in my book?
Think about all the fiction you've read that refers in passing to real companies, brands, sports teams, games, and so on. All of those things have trademarked names, yet you can have a character drink a can of Coke while watching the Red Sox play before heading out to Cinemax to see the latest Star ...
(more)
6 months ago
Edit Post #37593 Question reopened 6 months ago
Edit Post #38382 Question reopened 6 months ago
Comment Post #34630 @Liquid, sorry for the off-topic comment but I don't have another way to contact you. You were running writing challenges (opening line, word, theme...) over on SE; would you be interested in restarting them here? If so, could you leave me a comment at https://writing.codidact.com/questions/39558#an...
(more)
6 months ago
Comment Post #37838 Yes! Fairly often for me, it is the process of writing an explanation of something that uncovers the gaps in my own understanding of that thing. The mere act of explaining something can push you to learn more about both the subject area and the craft of explaining it (writing, teaching, etc).
(more)
6 months ago
Comment Post #74810 Ooh, I hadn't been thinking of access-restricted categories. Interesting idea! I'll need to discuss that with the developers. (If it's visible to registered users only, that should address the search-engine concern.)
(more)
6 months ago
Comment Post #74807 I agree with that: proactive posts not questions, and use tags to categorize things as applicable (e.g. tools, critique sites/groups, reference materials).
(more)
6 months ago
Comment Post #74807 That makes sense. How would you want to structure it? One Q&A per topic with answers suggesting resources, or something like articles (non-question standalone posts that don't have answers) that the community would edit, or something else? We have support for standalone post types coming soon (to ...
(more)
6 months ago
Comment Post #74801 On SE we sometimes had challenges and prompts, for the purpose of engaging the community more and perhaps trying forms we wouldn't otherwise have used. We used meta for this, which wasn't great. The works weren't things we were going to submit elsewhere. Since there was a suggestion to bring back ...
(more)
6 months ago
Edit Post #23795 Post edited:
updated link
6 months ago
Edit Post #74774 Post edited:
6 months ago
Edit Post #74769 Post edited:
6 months ago
Edit Post #39219 Post edited:
6 months ago
Comment Post #74769 This is now fixed.
(more)
6 months ago
Edit Post #74774 Post edited:
6 months ago
Edit Post #74774 Post edited:
updated for new UI; categories are more discoverable now
6 months ago
Edit Post #39197 Question reopened 6 months ago
Comment Post #39197 On SE, this question was closed as a duplicate of https://writing.stackexchange.com/questions/18591/is-it-okay-to-publish-a-book-at-a-young-age. However, something seems to have gone wrong with the import of that question here, possibly because it involves deleted users. I'm going to reopen this he...
(more)
6 months ago
Edit Post #74774 Post edited:
6 months ago
Edit Post #74774 Initial revision 6 months ago
Question Shall we showcase some of our fiction, poetry, and other work?
You might have noticed the new "categories" feature on this site. I mean this: screenshot of categories tabs What are categories? Categories are types of content -- main Q&A and Meta are the two that all sites share, but the feature allows sites to build other things too -- blogs, question sa...
(more)
6 months ago
Comment Post #39580 [Trust levels](https://github.com/codidact/docs/wiki/User-Privileges) will tie privileges to activity, but I suspect @Mark is looking for something a little more visible. To whit: instead of showing a rep number, which doesn't actually tell you whether this person has a few popular posts, a zillion 0...
(more)
6 months ago
Edit Post #39575 Initial revision 6 months ago
Answer A: Is there any popular wisdom on the word "seem"?
Your example is first-person narration in the past tense. That is, your narrator is reporting events that previously happened. At the time of the events, the narrator thought the walls were moving -- no "seemed" about it. But at the time of the narration, the narrator (presumably) realizes that ...
(more)
6 months ago
Comment Post #39572 @Ooker using someone else's reputation to promote your work without asking first is likely to annoy the person. I mean, it's one thing if you tweet "hey, look at this cool comment I got" or the like, but for less-spontaneous promotion, I would *strongly* urge you to ask first and be gracious if the ...
(more)
6 months ago
Edit Post #39219 Post edited:
updated for change in strategy
6 months ago
Edit Post #39572 Initial revision 6 months ago
Answer A: How to prove that my blog is just not average?
Assertions about quality from the creator of a work, whether it's a blog, a novel, a video, a podcast, or anything else, are not convincing because of the conflict of interest. Even if your work is the greatest thing since sliced bread, you saying it undermines the claim, because lots of people who ...
(more)
6 months ago
Edit Post #38434 Post edited:
6 months ago
Comment Post #39559 Ooh, I like that idea. When we have categories (let me ping the devs to find out how soon we can have that), then we could have a dedicated place to post our own writing, e.g. short stories, and the act of writing them would probably also generate main-site Q&A.
(more)
7 months ago
Edit Post #39559 Initial revision 7 months ago
Answer A: Have we ground to a halt?
I think your assessment is correct: we have lots of people here to answer, but we aren't seeing many new questions. Inertia is keeping the new questions mostly on SE. I, too, have been going through the lottery tab, casting votes and looking for things I can add useful answers to, but we need new q...
(more)
7 months ago
Edit Post #39549 Initial revision 7 months ago
Answer A: There is no accept button?
QPixel doesn't have an "accept" button, no. QPixel is a work in progress so it doesn't have everything SE has. QPixel is also a path toward Codidact, and Codidact won't have an "accept" button either. Why not? Which answer the asker of the question likes best isn't particularly significant ...
(more)
7 months ago
Edit Post #39522 Post edited:
7 months ago
Edit Post #39525 Post edited:
7 months ago
Comment Post #39525 @xtal it got fixed between my post and your comment. I'll edit.
(more)
7 months ago
Edit Post #39525 Initial revision 7 months ago
Answer A: Design changes are a-coming!
Edit: fixed. The font face and size make posts too hard to read (and also, I'm now discovering, to compose). The current font face is vertically "squashed"; this is not the Arial or similar that we used to have. This face is harder to read, especially when combined with: The body text size ...
(more)
7 months ago
Comment Post #39524 Test comment to confirm bug report. Confirmed!
(more)
7 months ago
Edit Post #39522 Post edited:
7 months ago
Edit Post #39522 Initial revision 7 months ago
Answer A: Design changes are a-coming!
Edit: fixed. Thanks for the update and the announcement. We seem to have lost our Writing-specific header graphic in the migration; it's been replaced by a QPixel logo. May we please have our graphic back? I see that Codidact Meta has its icon, so it's not a general problem. (Also, the fav...
(more)
7 months ago
Comment Post #39512 I wonder whether SciFi objects to an ad for us or to that specific ad. Is it worth trying another ad with simpler art? (Could be the same quill-pen art as on most of the other sites.)
(more)
7 months ago
Edit Post #39509 Post edited:
7 months ago
Edit Post #39509 Post edited:
7 months ago
Edit Post #39510 Initial revision 7 months ago
Answer A: Advice for indicating sources in tables
A core principle with citation is: if you say it's from source X, it must be exactly what's in source X. Not a summary. Not a translation. Not a refactoring. By citing a source you are invoking that source's authority, in a sense; by adapting a work but citing it without noting the adaptation, yo...
(more)
7 months ago
Edit Post #39509 Initial revision 8 months ago
Question Ads for this community
One of our community members, Paulster2, has created some ads and submitted them on SE sites where we've advertised in the past. These are "community promotion" ads, meaning the SE communities vote on them and that decides what ads are shown. This year the ads are similar but the URL is different. ...
(more)
8 months ago
Comment Post #39499 I agree with this answer. The software running this site now supports multiple communities, so a worldbuilding community here alongside our new writing community is quite possible. It just needs people to support it.
(more)
8 months ago
Edit Post #39493 Initial revision 8 months ago
Answer A: Documenting framework features and descriptions
If you are documenting programming interfaces (APIs), look for a tool that generates documentation from comments in the code. This allows you to place the documentation right with the code, and the tool extracts the function interfaces from the code directly. This means there's one source of truth,...
(more)
8 months ago
Comment Post #39438 See also the "lottery" tab, which provides a random sample of older questions (I think it's a daily refresh).
(more)
8 months ago
Comment Post #39438 Welcome! Your posts came through, but we have no way to copy votes so all scores reset to zero. (Otherwise you'd have no way to know whether you'd already voted on something and might end up double-voting.) I suggest browsing posts "connected" to yours (like answers to your questions, other answer...
(more)
8 months ago
Comment Post #39437 Duplicates are kept (not deleted) specifically because of what you say -- people ask questions in different ways so don't find the original via search, and the duplicate links help bring them together. The "cluster" idea is interesting; right now we have unidirectional links, and that seems like som...
(more)
8 months ago
Edit Post #38520 Question reopened 8 months ago
Comment Post #39414 Thank you for this input (definitely not useless!). One reason we didn't import the votes is that we can't connect them to users; from the data dump we can only tell *how many* votes (in each direction) a post had, but we can't tell where those votes came from. Rather than having people voting twic...
(more)
9 months ago
Comment Post #39404 I don't think publishing is categorically off-topic. Writers need to understand what publishers are looking for, how they will advertise your book, etc. And questions about finding an agent (as opposed to specific solicitation of same) should be welcome. Also, some writers self-publish and that me...
(more)
9 months ago
Comment Post #39408 Sounds like a great idea!
(more)
9 months ago
Edit Post #38848 Post edited:
9 months ago
Comment Post #39357 For *now*, the same scope guidelines we used on SE apply. As we move forward, and particularly when we move onto the Codidact platform which will give us some new capabilities, we can refine. I intend to create some help topics but won't be able to do so before the end of Shabbat, sorry.
(more)
9 months ago
Comment Post #39355 I wonder how often people look beyond the first page. If there are 360ish pages but we mostly look at the first one, then the old stuff is there but unnoticed until somebody does a search or looks at something from someone's profile. Maybe that's ok *but* we should try to improve what we find when ...
(more)
9 months ago
Edit Post #39353 Post edited:
Creating tag -- textbooks, being instructional and with assignments, are different enough to warrant a tag.
9 months ago
Comment Post #39340 Just in case I wasn't clear, with this meta post I'm more focusing on the bootstrapping issue with our large body of imported content. I'm not talking about new content or site policies months from now.
(more)
9 months ago
Comment Post #39336 Yes, agreed -- deletion is part of curation, but so is editing and even writing new (better) answers to old questions. I was trying to address curation in all its forms; sorry for being unclear.
(more)
9 months ago
Comment Post #39336 I am talking about curation, yes. On Stack Exchange, high-rep users can vote to delete. Here we don't have that; only moderators (I think) can delete, so to *implement* this type of curation we need moderator action. (By the way, you might be interested to know that Codidact is planning a differen...
(more)
9 months ago
Edit Post #39333 Post edited:
I don't seem to know how to do footnotes here; <sup> doesn't seem to be it.
9 months ago
Edit Post #39332 Post edited:
9 months ago
Edit Post #39333 Initial revision 9 months ago
Question How shall we handle our old (imported) content?
When we created this site, I made the executive decision to import all our content from Stack Exchange instead of starting with a blank slate. I did that for a few reasons: - We have a lot of good content there, and we should continue to have ready access to, and curate, that content. - I felt...
(more)
9 months ago
Comment Post #39331 Also, sorry about the password problem! This current site is a stopgap, to keep our community from falling apart over on SE. Better software is coming, but we could get this now. We're depending on the servers and caretaking of one person -- a reliable person, but one person nonetheless, and we do...
(more)
9 months ago
Comment Post #39331 A lot of questions have some nuance that makes the new one different from the older one anyway. My recommendation: ask the new question, and if it turns out to be an exact duplicate the community can mark it as such. If you know about the older question (or someone points it out), you can edit to e...
(more)
9 months ago
Edit Post #15438 Post edited:
9 months ago
Edit Post #15436 Post edited:
9 months ago
Edit Post #15436 Question reopened 9 months ago
Edit Post #5186 Post edited:
9 months ago
Edit Post #39328 Initial revision 9 months ago
Answer A: How to use professional jargon when writing fiction?
Handling realistic jargon that your readers might not know is similar to the problem described in Using real words from a foreign culture feels like 'Calling a rabbit a "smeerp"', a question about fantasy language. In an answer there I pointed out that density is one problem; if every fifth word in ...
(more)
9 months ago
Edit Post #23442 Post edited:
Clarified title; I was mentally composing an answer until I got to the end of the question and realized it was about in-person groups specifically.
9 months ago
Edit Post #39327 Initial revision 9 months ago
Answer A: How do you track dependencies for your co-authors?
I've changed teams (and companies) since asking this question years ago, and the doc set is even larger on my current team. Here's how we manage changes that affect parts of the documentation with different primary/responsible writers. First, we do use source control as mentioned in another answe...
(more)
9 months ago
Comment Post #39324 We had to choose between a blank slate (which also wouldn't have looked great) and importing content. If the content is good, I think it's worth having even if scores are currently 0 because no one's voted yet. We can work on that.
(more)
9 months ago
Comment Post #39324 @Amadeus this site is a stopgap, a place where our community can continue where we left off while waiting for the more "solid" platform that we hope to move to but doesn't exist yet. Please do continue to look at questions and answers here, vote, improve where you can, and otherwise build things up....
(more)
9 months ago
Comment Post #39324 I think right now we do have that band of regular users who don't have specific questions *right now* but love the topic and want to help build this repository. SE will get the Googlers but we can build a community here too. There are a lot of old questions that are timeless in nature and could be ...
(more)
9 months ago
Comment Post #39321 That sounds good -- how often are people going to read more than 25 questions at a time anyway?
(more)
9 months ago
Edit Post #39319 Post edited:
9 months ago
Edit Post #39319 Post edited:
can't make the markdown play well with the underscores in the name, so just removed it
9 months ago
Edit Post #39319 Post edited:
9 months ago
Edit Post #39319 Initial revision 9 months ago
Answer A: How can I highlight changes in HTML output from Flare, based on branch diff?
We did not find an off-the-shelf solution to this and built our own. I'm not the author and can't release the code, but here is an overview of the approach. Flare versions from 2016 onward support adding pre- and post-build steps to a build target. We modified our "branch build" target to call o...
(more)
9 months ago
Edit Post #39318 Initial revision 9 months ago
Answer A: Questionable Promotions!
I think this would particularly help in this "new site, imported content" stage. There are a lot of questions and answers that are old and valuable. They all started here at score 0 (that's by design), and some of those questions would almost certainly benefit from new or updated answers if we saw ...
(more)
9 months ago
Comment Post #39314 I recently read *Autonomous* by Annelie Newitz, and it did a great job of following multiple protagonists that were headed on a collision course. They weren't working together like in the OP's question, but the author portrays each of them positively and with some depth, and even though some of them...
(more)
10 months ago
Comment Post #39311 Sorry about that @Mark; I meant the text at the link I posted is for Codidact, not specifically Writing.
(more)
10 months ago
Comment Post #39304 The challenges come up when the discussion is relevant and someone feels uncomfortable; in those cases the focus should be on *how* we talk about the topic, and a mod might need to remind people about depersonalizing etc. (2/2)
(more)
10 months ago
Comment Post #39304 When I'm moderating and somebody raises concerns about something, I ask myself if the discussion is *necessary*. I mean, if somebody's talking smack about a group (any group) in a chat room about, say, technical writing, that's pretty easy -- this is off-topic, someone's uncomfortable, let's chill p...
(more)
10 months ago
Edit Post #39215 Post edited:
10 months ago
Comment Post #39307 I believe we can validate Mark's user number from [this post](https://writing.stackexchange.com/a/27869), which cites (and links to) a book that he wrote.
(more)
10 months ago
Comment Post #39305 Sorry for the confusion. I think you got caught by the two different versions of the "ask" button. Hey, it's a work in progress...
(more)
10 months ago
Comment Post #39305 Hmm, that didn't work -- tried to move this to meta by editing the title, but no luck. Since there are no answers yet, how would you feel about reposting it there and deleting this version? (Go to the "meta" tab and click on "ask meta question".) Including your SE user number from your comment wil...
(more)
10 months ago
Edit Post #39305 Post edited:
10 months ago
Comment Post #39304 Related discussion on the Codidact forum: https://forum.codidact.org/t/proposed-code-of-conduct/462/95?u=cellio. It's a long thread; I've linked to the message that quotes the latest version (proposed by Art). This is proposed language for the Codidact network (specifically, the one this group of d...
(more)
10 months ago
Comment Post #39219 @DPT you can post a meta question or report an issue on GitHub (link in Art's answer). Welcome aboard and sorry you've run into a problem. Please provide details in your report.
(more)
10 months ago
Comment Post #25665 This is approximately what we did. We wrote some JavaScript to do Google Docs-style commenting (select some text, click the "comment" icon that pops up, type). Places with comments are highlighted and you can click or hover to see the comment. A page in the build shows all comments with links. Co...
(more)
10 months ago
Comment Post #39220 @user8078 to add to what Art said, posts that were created here don't have it, and posts that were imported from SE and then claimed by users here don't have it. The latter is because those users have given us a direct license for their content (by claiming it), so the chain of authority now goes ba...
(more)
10 months ago
Comment Post #39287 For anybody interested, I just made [a proposal for handling meta in Codidact](https://forum.codidact.org/t/proposal-meta-is-just-another-post-type/451), partly inspired by how meta works here (plus the issues we all experienced with meta on SE). I hope Writing will move onto the Codidact platform w...
(more)
10 months ago
Comment Post #39275 @ArtOfCode much better! Just one thing: please spell out "SFW". I know what it means and you know what it means, but let's not assume every visitor will.
(more)
10 months ago
Comment Post #39275 Auditability is the antedote to relying on moderator discretion. So long as (a) other moderators can review and (b) the recipient of a sanction has an escalation path, I think we'll be ok. Granted we don't really have the latter right now (other than a public complaint), but ultimately I hope our s...
(more)
10 months ago
Comment Post #39271 Welcome @Caleb. If you of a more technical bent, we do have questions on technical writing, API documentation, (code) examples, and more. Also scientific and academic writing.
(more)
10 months ago
Edit Post #35532 Post edited:
10 months ago
Comment Post #34684 @Lauren that's very closely related and maybe they should be dupes, but that one asks only about formatting while this one asks a slightly broader question, how to indicate it (which isn't just formatting, as I suggested in my answer). I wonder if we should close the other one as a dupe of this one?...
(more)
10 months ago
Comment Post #34684 Related: https://writing.codidact.com/questions/35006
(more)
10 months ago
Comment Post #35006 Related, on telepathy: <a href="https://writing.codidact.com/questions/34684">https://writing.codidact.com/questions/34684</a>.
(more)
10 months ago
Edit Post #39275 Post edited:
added suggestion from comment
10 months ago
Comment Post #39275 That works. I want to see one bullet point, not one page -- it's disproportionate otherwise. There are all sorts of behaviors that are problematic; expanding at length on one of them is problematic, and expanding on *all* of them at length is differently-problematic. Let's keep it short and sweet,...
(more)
10 months ago
Edit Post #39275 Post edited:
10 months ago
Edit Post #39275 Initial revision 10 months ago
Answer A: A Code of Conduct, dare I say it
I was hoping that our code of conduct could be something closer to the "be nice" model, something like this: - Be respectful and polite. - Presume everyone else is doing so, too. - Be open to constructive feedback. - Well-meaning people on a worldwide, multi-cultural platform can accidentally...
(more)
10 months ago
Edit Post #39219 Post edited:
10 months ago
Comment Post #39220 I don't know that this rates a full FR so I'll ask here and you can tell me if you want it elsewhere: could we have date/timestamps on comments? it helps with the "oh, that was before that clarifying edit; no wonder I'm confused" cases.
(more)
10 months ago
Comment Post #39267 Heh. :-) (And if I'd checked chat before posting this I'd've known that. Sorry.)
(more)
10 months ago
Edit Post #39266 Initial revision 10 months ago
Question Question list shows activity that I can't find
This might be related to this issue, which is sort of the reverse of the one I'm reporting now. According to the front page, ArtOfCode did something on this question an hour ago (as I write this). But I can't find it. Here's the history for the question: ![screenshot][1] It's my question, ...
(more)
10 months ago
Edit Post #10921 Post edited:
added link for the open-source tool (people already know how to find Visio)
10 months ago
Edit Post #39257 Initial revision 10 months ago
Answer A: How do we distinguish someone talking to another person via telepathy rather than via vocal means?
The first step is to use different styling for the telepathic parts, as suggested in the answer by Evil Sparrow. I recommend against using italics because italics are often used for inner dialogue (thoughts). But it's not just styling; go deeper. Telepathy is a different kind of communication, s...
(more)
10 months ago
Edit Post #34684 Question reopened 10 months ago
Edit Post #39248 Initial revision 10 months ago
Question What are our plans for image uploading?
I needed to include screenshots in this question but didn't see a way to add them directly. I uploaded those to imgur so I could post, but that's not the ideal solution. (You'll see why if you look at where on imgur I uploaded them.) Where is image-hosting in the roadmap? If it'll be a while then...
(more)
10 months ago
Edit Post #39247 Initial revision 10 months ago
Question I answered a question 2 hours ago, but the front page says the last activity was 8 hours ago.
According to the question list, this question was last active 8 hours ago as I write this: ![screenshot][1] However, I answered it 2 hours ago as shown in the history on my answer: ![screenshot][2] Is this list heavily cached (I assume there's some caching), or is something else going on?...
(more)
10 months ago
Edit Post #39246 Initial revision 10 months ago
Answer A: How do we follow up a description within a descriptive text with another description?
I endorse Evil Sparrow's answer. If, however you must lead with the old man for some reason, you can return from the room back to him with a paragraph break. Paragraph breaks are (small) discontinuities and you should use them when changing subjects, just as you do when changing speakers in dialogu...
(more)
10 months ago
Edit Post #39245 Initial revision 10 months ago
Question Could the question list show what the most recent activity was (and by whom), rather than the author of the question?
I've realized in using this site how dependent I am on the information on the SE question list about who and what bumped a post. "Answered by" + name is a valuable "hey, go read this!" clue, as does "modified by" + name I don't recognize as recently active on that question. Further, a lot of questi...
(more)
10 months ago
Comment Post #39233 Yes, meta questions should appear (we want people to notice and come to meta), but labeled.
(more)
10 months ago
Comment Post #39219 Great to see everyone here!
(more)
10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #26048 Post edited 10 months ago
Edit Post #25899 Post edited 10 months ago
Edit Post #27469 Post edited 10 months ago
Edit Post #36928 Post edited 10 months ago
Edit Post #39226 Initial revision 10 months ago
Answer A: Alternatives to second-person POV narration in RPG settings
In your first example, all three of your sentences focus on the effect. Instead, mix in some descriptions of the cause. Instead of: > You have a feeling of immense dread as you take in the macabre sight > You are reminded of your own mortality as you witness the gruesome murder of Sir Importa...
(more)
10 months ago
Comment Post #35643 Yes, if the script is unfamiliar, then the reader will interpret all cases of it as "blob of that other alphabet", and unless phrases are very different in length, will often not notice if this blob is the same as a previous one.
(more)
10 months ago
Comment Post #39220 @Art, it's behaving correctly for me in Chrome on my Mac. I don't know what the difference is. (I did disable userscripts in Firefox to check for that; made no difference.)
(more)
10 months ago
Comment Post #39220 @Art with the web console open, when I click on an item in the inbox I get "TypeError: NetworkError when attempting to fetch resource.". (Dunno what that means. I mean, I know what all those English words mean, but...)
(more)
10 months ago
Comment Post #39223 On the avatar, did you save the profile after? You have to both choose the file (using those buttons) and then use the "save" button at the bottom for the profile edit.
(more)
10 months ago
Comment Post #39220 @Art that's what should happen, but it's not for me currently. (Firefox, Windows -- I'll try a different browser/machine later. My (now) three most recent notifications are not dismissing.
(more)
10 months ago
Comment Post #39220 @Art are your inbox notifications overly sticky too, or is it just me? (The notification for Thomas's comment on the question here isn't going away for me. Don't know if it's something on my end or not.)
(more)
10 months ago
Edit Post #25663 Post edited 10 months ago
Edit Post #33955 Post edited 10 months ago
Comment Post #39219 Welcome @Neil! (I don't know if we have comment pings yet.)
(more)
11 months ago
Edit Post #39219 Initial revision 11 months ago
Question Welcome to Writing on Codidact!
Welcome to a new home for the Writing community. Please use it, report problems and make requests on Meta, and collect your thoughts about what we need to support our community. This site is running on beta software that will eventually become Codidact. We started with a Q&A platform that alread...
(more)
11 months ago
Answer A: How do I cite previously published print school newspapers on now online school newspaper?
Print publications that are no longer in print are (were) still print publications. You would therefore cite them the same way you would any other newspaper article from a still-extant paper. (Citation format varies by style guide.) However, if you only accessed it via an intermediary, like a compila...
(more)
about 1 year ago
Answer A: How to eliminate standoff between "Lengthy" vs "Concision"?
"Concise" doesn't mean "very short"; it means "no more verbose than it needs to be". In your case, you have needs that establish a minimum length. Trying to fight against that will only lead to frustration, as you've seen. If people are using this document as a basis for implementation, it's better t...
(more)
about 1 year ago
Answer A: Compelling story with the world as a villain
A villain has intention -- it's out to cause some outcome, foil the main character (if it's personal), and generally advance its own agenda. The world, on the other hand, just is, barring worlds with minds and will. It sounds like you're trying to write a person-versus-nature (or society) story rathe...
(more)
about 1 year ago
Answer A: How to write a sincerely religious protagonist without preaching or affirming or judging their worldview?
Show his religious practices more and his explicit beliefs less. What does a devout Catholic do? Probably he doesn't spend all day talking about his beliefs; instead he lives them. He tithes. He fasts on Fridays. He attends mass daily before going to work (or wherever he spends his days). He teaches ...
(more)
about 1 year ago
Answer A: Referring to different instances of the same character in time travel
The Magic 2.0 series by Scott Meyer has this situation with a core character (so it's not a passing situation). The narrator and the characters identify the two as Brit the Elder and Brit the Younger. When more time-travel shenanigans happen, we also encounter Brit the Even Elder and Brit the Much Yo...
(more)
over 1 year ago
Answer A: How to write a good moderator nomination post?
A nomination post is basically a sales pitch, packed into 1200 characters. You need to persuade readers that you are or might be a good choice in a few hundred words (give or take). So a nomination is longer than an "elevator pitch" but shorter than a full bid. Therefore, don't think of your nominat...
(more)
over 1 year ago
Answer A: Character had a different name in the past. Which name should I use in a flashback?
The reader needs a connection when transitioning into the flashback. That transition can be either external or internal. By external, I mean introducing the flashback. In this case, the reader knows who's in the flashback so you can use the then-current name without any more explanation. For example...
(more)
over 1 year ago
Answer A: Is there a need for better software for writers?
IDE-like tools exist for writers. Scrivener is a powerful general-purpose tool (also with questions here). Madcap Flare, aimed at technical writers, has good support for updating links, defining "snippets" (xinclude blocks, essentially), variables, conditionalization, advanced build options, and more...
(more)
over 1 year ago
Answer A: Do publishers care if submitted work has already been copyrighted?
If you live in a country that is a signatory to the Berne Convention (most countries are), then your work is copyrighted as soon as you create it, regardless of whether you go through any registration process. To a publisher, your work is already copyrighted, and if they want the copyright and not ju...
(more)
over 1 year ago
Answer A: How can I effectively research for a high-fantasy setting?
> Base parts of the setting on real world cultures or locations. Unless you have near-infinite time to do your worldbuilding, you're probably going to keep coming back to our world. So start there! Not in the sense of "modern-day Earth with the serial numbers filed off", but in the sense of specific...
(more)
over 1 year ago
Answer A: What is a more techy Technical Writer job title that isn't cutesy or confusing?
This is a challenging specialization to capture in a job title, which is why my LinkedIn tagline says "speaker to programmers". But that doesn't work as a job title at any but the edgiest startups. As suggested in this answer, some use Programming Writer. At a previous company I was documenting but ...
(more)
over 1 year ago
Answer A: Should one blog in a few languages?
Writing a full translation will approximately double the time you spend creating each post, so as other answers have said, you'll need to consider the cost versus benefit. However, thee's another approach you could take: keep writing in your native language and provide a summary in the other language...
(more)
over 1 year ago
Question How should we plan for translations' space needs when designing diagrams that require text?
Our documentation set includes some diagrams where text is integral and can't be handled in callouts, like flowcharts and entity relationship diagrams. Our documentation is translated, so these diagrams need to be translated too. But diagram design is informed by the amount of text we need to include...
(more)
over 1 year ago
Question How can we make images with (necessary) text more translatable mechanically?
Our documentation set includes some diagrams, such as entity relationship diagrams and flowcharts, where text is integral and cannot reasonably be handled in callouts. Our documentation is translated into another language, so these diagrams ought to get translated too. (I don't know if they currently...
(more)
over 1 year ago
Answer A: How much episode recap is necessary in a tv-focused podcast?
You said in a comment that this is for an existing, old show, presumably one with a fanbase. While your listeners have presumably seen it (they're listening to your podcast about it, after all), they might not have done so recently and even hardcore fans might not always remember episode sequencing (...
(more)
over 1 year ago
Question How can I make names more distinctive without making them longer?
In the point-of-view culture in my story, all of the women in priestly families have two-syllable names beginning with vowels. (There are reasons for this, but they're completely tangential to my question.) I've gotten feedback from a beta reader that the character names look/sound too similar, even ...
(more)
over 1 year ago
Question When blogging recipes, how can I support both readers who want the narrative/journey and ones who want the printer-friendly recipe?
Increasingly often, if you Google for a recipe your search results will be full of long, image-rich blog posts that, somewhere in there, have the actual recipe you were looking for. Many of these have a "printer-friendly version" link to make that easier; I can get the stuff I need in my kitchen on p...
(more)
over 1 year ago
Answer A: Making science for toddlers easy to remember
It's been decades since I was a kid watching cartoons on TV, and I can still sing some of the Schoolhouse Rock songs. Schoolhouse Rock, for those unfamiliar with it, was a series of short (2-3 minute) bits of educational programming interspersed among Bugs Bunny, Road Runner, Bullwinkle, et al. Each...
(more)
over 1 year ago
Question For HTML documentation sets, are there meaningful guidelines for topic length?
We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics -- that is, sub-pages in the table of contents -- the TOC automatically expands to show them. Because our ...
(more)
over 1 year ago
Question Adding tags to documentation built in Flare?
Our software documentation set (for a SQL analytics database platform) is large, because SQL and databases have many pieces. Often a single statement, function, or feature will be highly related to a few others, and in the past people have (manually) added "related information" sections to pages to m...
(more)
over 1 year ago
Answer A: What is special in API documentation compared to general technical writing?
API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to someone who's trying to accomplish some task, and while some of those people (and tasks) are deeply techni...
(more)
over 1 year ago
Answer A: Should I create a domain name using a pen name that is common with another person's domain name?
Names are almost never globally unique. This is true whether the owner chooses or the owner's parents do. Author Alex Feinman even has a note on his web site (.net) saying "looking for the other one? that's .com" with a link. If you search Google or LinkedIn for a name, odds are good you'll find more...
(more)
over 1 year ago
Answer A: Symbolism of 18 Journeyers
I see two parts to your question: signaling that 18 is significant, and signaling why it is significant. Assuming that you'll have Jewish readers too, don't skimp on the first part -- you want to give them something to notice and figure out, too. Another answer addresses ways to show why 18 is signi...
(more)
over 1 year ago
Question How can I highlight changes in HTML output from Flare, based on branch diff?
We use Madcap Flare for a large documentation set, with HTML output. (Flare source is a very HTML-y XML with some Flare-specific additions.) We use git for source control and new work is done on branches. This means that at the end we have a git pull request (PR) that can show a diff between the bran...
(more)
over 1 year ago
Answer A: Should I use acronyms in dialogues before telling the readers what it stands for in fiction?
If you don't provide a hint, then readers will know only that somebody requested a meeting and that's considered an emergency. If you want to convey something about the nature of the organization (or emergency) you need to provide more of a hint, but that doesn't necessarily mean expanding the acrony...
(more)
over 1 year ago
Answer A: How to include external references when writing internal documentation?
The guiding principle in my experience is: put the link where the reader needs the referenced information. Examples: - "This interface is like Somebody Else's Thing (link, or make SET a link itself), and in addition..." -- put the link right there, because somebody unfamiliar with SET will need to a...
(more)
over 1 year ago
Answer A: Do we need to make consistent use of archaic English in our poem/novel?
Regardless of what you're writing, if you use an archaic form readers will notice, and if you use an archaic form only once and not everywhere it applies, readers will notice that too. If you're doing it for effect, you've achieved your goal. This is sometimes the case in poetry. On the other hand, i...
(more)
over 1 year ago
Answer A: Including disabled characters without "inspiration porn"
You avoid it by showing us a whole, three-dimensional character with attendant complexity. Doing great things is not about one thing. Your character has a mix of traits, talents, interests, inclinations, genes (if it's that kind of magic), and more, and uses all those things to deal with all obstacl...
(more)
over 1 year ago
Answer A: How do we edit a novel that's written by several people?
The first step is to work out some style guidelines among yourselves. Agree on what style you want the finished product to follow. Because this is a project among friends rather than, say, a corporate publication, you'll probably end up including aspects of each writer's style while moving the whole ...
(more)
over 1 year ago
Question How large should photos on my blog be?
I sometimes post photos on my blog, like when I'm blogging about food. I've been shrinking the huge pictures my phone takes down to a size that fits more reasonably in a browser window -- my browser window, so far -- because I don't want my posts to require a huge window. Recently I've noticed that t...
(more)
over 1 year ago
Answer A: What is in scope for criticizing technical writing
This answer covers a single work like a paper well, and what it says applies to larger works too. Correctness and clarity are the most important factors in any technical work. For larger works, such as a new section in a large documentation set, I look for some additional things: - Consistency of st...
(more)
over 1 year ago
Answer A: How to tag distinct options/entities without giving any an implicit priority or suggested order?
Full names and arbitrary names are good solutions to the question you asked. To address the question behind the one you asked -- the implicit "superiority" in ordering -- write examples that don't start with the first unit. For example, I might describe a database with nodes A, B, and C, and then tal...
(more)
over 1 year ago
Answer A: Can I write a book of my D&D game?
Plagiarism would be taking exact text from the various game manuals and representing it as your own. So don't do that. But you probably weren't going to anyway, because you want to tell a story, not publish a game log. Think of your story as being inspired by your game, but retell it as a story. Whe...
(more)
over 1 year ago
Answer A: Consulting experts - why should they talk to someone who isn't a published writer yet?
I've got nothing on shadowing (I suspect that's a very hard sell), but for asking questions, there are two (non-exclusive) approaches that I've seen and occasionally been part of (on both sides). The first is to start with your own circle of friends. I'm not a radiologist, lawyer, chef, schoolteache...
(more)
over 1 year ago
Answer A: Methods for writing a code review
How you structure a code review depends on the tools you're using and the level of scrutiny that was requested. Instead of giving you an exact template, therefore, I'll address the different types of content. At the lowest level, a code review can include feedback on individual lines or sections of ...
(more)
over 1 year ago
Answer A: What language shall they sing in?
These are songs, and we learn songs differently from spoken language. Have you ever found yourself singing along to a favorite song in a language you don't even speak, but you've listened to the recording enough to have memorized it? You were almost certainly helped by meter and perhaps rhyme, by the...
(more)
over 1 year ago
Answer A: Strategies for writing software design documents
This answer provides a lot of good information. I want to augment it, not compete with it. Over time, many organizations develop templates for various documents (design, functional spec, test plan, etc). Often they're derived from IEEE standards -- usually, in my experience, they're simplified from ...
(more)
over 1 year ago
Answer A: How soon is too soon for a redemption arc?
The light is inside him; it just needs a path out. Not a big gaping doorway that opens all at once, but small tendrils. Think "many drips carve a rock", not sudden change. How do you do that? In a lot of fiction that I've read (and I suspect there's psychology behind this, but I don't know), the fir...
(more)
over 1 year ago
Question How can I start in media res and provide enough back-story to hook people, all in the first chapter?
My story (novella?) starts in media res, in the middle of the conflict that will set the rest of the story in motion. Currently I am "scene-cutting" between that event and some earlier events that provide context. The current sequence for the first chapter is: - main character #1 and main antagonist...
(more)
over 1 year ago
Answer A: An LGBT main character, but the book isn't about LGBT issues
One way to keep it from taking over your story is to make it unexceptional. Quite literally. Kem is nonbinary. If Kem, other characters, and the narrator don't make a big deal out of that, don't either hide it or gawk at it, and just go about their lives, you'll convey the message that this is normal...
(more)
over 1 year ago
Answer A: Avoiding repetition when there are two unidentified individuals
You can look for other ways to identify the characters. For example: > The tall figure stood in the corner, towering over the unmoving skinny figure in the chair beside it. It moved away from the seated figure to the opposite side of the room and began palpating the wall as if looking for something....
(more)
over 1 year ago
Answer A: I'm afraid that my setups will be overlooked
Setups are most rewarding when the reader realizes after the fact that that detail was important but doesn't figure it out too early (i.e. it's not more obvious than you wanted it to be). If a reader gets to the reveal without prior hints, that comes across as deus ex machina. If a reader gets to the...
(more)
almost 2 years ago
Answer A: How to keep darkness from piling up
Have a lighter "B" plot. Yes, your main character is getting deeper and deeper into a dark place because of the struggle with the evil overlord -- and in the midst of it all she also finds herself caring for her ex's rambunctious puppy. Tell the story in a way that offsets the mood of the events. A ...
(more)
almost 2 years ago
Answer A: Do I quote the author or artist from a comic? MLA
The MLA doesn't have a definitive statement on this. In an entry about citing speech bubbles from comics they show an example that includes only the author, but the book itself doesn't credit an artist on the cover so that doesn't help. I found several academic sites that give the same MLA guidance f...
(more)
almost 2 years ago
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 2 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 2 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 2 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 2 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)
about 2 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 2 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 2 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 2 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 2 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 2 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 2 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 2 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 2 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 2 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 shou...
(more)
over 2 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 2 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)
over 2 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 informed ...
(more)
over 2 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)
over 2 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 2 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 2 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 2 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 2 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 2 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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)
almost 3 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 3 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 3 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 3 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)
about 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
almost 4 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)
about 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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)
over 4 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 4 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
almost 5 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)
about 5 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)
about 5 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)
about 5 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)
about 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 years ago
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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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)
over 5 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 5 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
almost 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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)
about 6 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 g...
(more)
about 6 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)
about 6 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)
about 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
over 6 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)
almost 7 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)
almost 7 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)
almost 7 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)
almost 7 years ago
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)
almost 7 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)
almost 7 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)
almost 7 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)
almost 7 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)
almost 7 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)
almost 7 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)
almost 7 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)
about 7 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)
about 7 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)
about 7 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)
about 7 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)
about 7 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)
about 7 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)
about 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
over 7 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)
about 8 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)
about 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 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)
over 8 years ago
Answer A: How do you avoid the problem of a collaborative work having separate voices?
For fiction that can accommodate different POVs, dividing those up per author not only addresses this problem but can be a feature. For cases where you want a unified voice, if you can't get a tough editor like Lauren Ipsum suggested, try having the authors edit each other's sections. Or, as noted...
(more)
over 8 years ago
Question How do you track dependencies for your co-authors?
I and one or more co-authors, sometimes geographically distributed, are working on a set of related documents. Sometimes I will make a change in my part that affects someone else's part; this could be anything from changing a name to adding a new concept (that later parts should then use or reference...
(more)
over 8 years ago
Answer A: LaTex vs. Word vs. etc
Any text-based "markup" format -- LaTeX, HTML, various XML schemas like DocBook, etc -- will serve you better than binary formats like Word, Pages, FrameMaker, etc. (I am aware that some of these tools export XML or SGML.) The reasons include: - Decoupling from editors. You can use your favorite too...
(more)
over 8 years ago
Answer A: How can I revise these sentences to be more correct while still keeping the effect?
The second sentence feels grammatically incorrect because it's not a sentence; it's two fragments joined by a semicolon. That doesn't make it wrong, but that's probably why you're reacting that way. If you want to keep the fragment style, I would tweak it thus: > Or perhaps not despite -- perhaps b...
(more)
over 8 years ago
Answer A: How to write about things which depend on each other
There are two general approaches, depending on the amount of detail you need from the "other" concept. If you don't need a lot, write about subject A, and when the first interaction with B hits add a parenthetical sentence, call-out note, or footnote (depending on your style guide) describing the ot...
(more)
almost 9 years ago
Answer A: What are the challenges of converting blog content to a publishable work?
Books compiling previously-published articles are not new. The usual challenges there are selecting and organizing your material and editing it for a different audience. Compiling material that is still readily available (blog posts) adds one more challenge: how do you induce people to pay for what t...
(more)
almost 9 years ago
Answer A: Is it acceptable for a book to not have a dominant lead character?
Movies and television shows can have ensemble casts; why not books? I've seen this in SF/fantasy books where the ensemble is the members of an adventuring party, the crew of a ship, etc; often there are 3-6 core characters. The novel 1632 (and successors) has many more important characters than I'm ...
(more)
about 9 years ago
Answer A: How can I express this more clearly or concisely?
Edited based on comments: Given the following function declaration: > f\get\vend\code(v\nut\id varchar2) return varchar2; I would write the description as follows: > This function takes a nut ID (NUT\ID) and returns the vendor's seller code (WINGNUT\SELLER\CODE) for this form. If NUT\ID is not se...
(more)
about 9 years ago
Question How can I manage screen shots and other graphics for maintenance?
Our 1500-page documentation set contains numerous screen shots and related graphics (schematics, flow diagrams, etc). Sometimes the user interface changes and we have to update all the affected graphics. The affected graphics are not necesarily all in one book; they can be spread across several. In s...
(more)
about 9 years ago
Answer A: What's the proper etiquette/format for updating a blog post?
For inconsequential changes you can just edit it. For anything substantial ("I meant to say I disagree with..."), I've often seen an explicit notation: "Edited to add: ..." "Edit: ...", or the like. If there have been relevant comments, you can include a timestamp for the edit so people will see it w...
(more)
about 9 years ago
Answer A: Does a technical writer need a technical background?
I am an experienced technical writer specializing in API documentation. In my experience, in order to be successful a technical writer needs enough technical aptitude to (1) understand the users' needs and (2) probe the subject-matter experts (SMEs). If all you're going to do is parrot what the SMEs ...
(more)
about 9 years ago
Answer A: Breaking Into Technical Writing - Where to Start (from a programming background)
There are different kinds of technical writing, differing in the "technical" part. The logical place for you to start, coming from a programming background like I did, would be with programmer-facing documentation: APIs, SDKs, and the tutorials and guides that go with them. If any of your current (p...
(more)
about 9 years ago
Answer A: What is the proper way to write a date containing two days in a row?
Either of those is fine ("&" is just another way to write "and") and will be understood. Another formulation you'll sometimes see is "Aug 4-5, 2011", but this is better for things that are continuous, like a convention. I assume your presentation will be in two parts, one on Aug 4 and the other on Au...
(more)
about 9 years ago
Answer A: Is it acceptable to mix how you address the reader in an instructional Wiki?
It would be bad style to publish documentation that did that, but since a wiki is designed to be edited by many people who will each have their own quirks and don't usually consult house style guides, doing this on a wiki probably won't raise eyebrows. That said, you should go back and change those ...
(more)
about 9 years ago
Answer A: When I'm replying to emails, what's the best way to acknowledge that I appreciated each point of someone's email?
There is no rule that you have to produce an equal volume of words in order for your correspondent to appreciate you. In fact, if you quote every sentence individually, inserting "I agree" or "good point" after each, that's going to lower people's impression of you -- it's a "me, too" reply, only wor...
(more)
over 9 years ago
Answer A: What style suggestions are common for which words are used in hyperlinks?
A link to the name is generally expected to link to the person, not to an article. I generally agree with @Craig Sefton, except that I would make "claims that pigs can fly" the link and not just "pigs can fly". It's a claim (by John Q), not a fact; "pigs can fly" could link to, say, a wikipedia page...
(more)
over 9 years ago
Answer A: Least possible editing effort if a text is for multiple media?
Any single-sourcing scheme is going to require some up-front setup in exchange for easier generation of multiple formats later. This Wikipedia page provides a starting point for process and tools.
(more)
over 9 years ago
Answer A: Technical Writing Software
As Viktor said, FrameMaker is probably the best widely-used tool for doing what you're trying to do. Another (Windows-only) tool that I'm using now is Madcap Flare, but it's pretty pricy. Other considerations: DocBook is a spec, not a tool (as Viktor said). It is XML, so you can use any XML editor ...
(more)
over 9 years ago