Activity for Monica Cellio
| Type | On... | Excerpt | Status | Date |
|---|---|---|---|---|
| Edit | Post #288778 | Initial revision | — | 3 months ago |
| Answer | — |
A: How do I know when I should rewrite vs. editing my first chapter The order in which the reader sees it is not necessarily the order in which the author wrote it. You can use this to get past rewrite loops or other blockers. When writing (both fiction and non-fiction), I sometimes insert "placeholders" -- I'm going to need a scene or section here that does X, Y... (more) |
— | 3 months ago |
| Edit | Post #288721 | Initial revision | — | 3 months ago |
| Question | — |
Should posting on Meta affect reputation? When we launched this community, we did not yet have the ability to set different reputation grants for different categories. We've had this for a while but we failed to follow up before now, sorry. Do you want us to change posts on Meta to not award rep for upvotes or subtract it for downvotes? ... (more) |
— | 3 months ago |
| Edit | Post #26634 |
Post edited: The imported post went through a migration, meaning the source we drew from had a name but no user account. To satisfy the spirit of the CC attribution clause, I'm adding the best info we have for the name. I wasn't able to backtrace to a user because of deletions at SE. |
— | 3 months ago |
| Comment | Post #286916 |
Was this cut/pasted from somewhere? The reference to "the library" in step 4 seems out of place.
As you're surely aware as someone who works with research papers, proper attribution is essential if you quote or copy someone else's work. If it's your own work that you're reusing, please take ano... (more) |
— | about 1 year ago |
| Comment | Post #283582 |
This is what we ended up doing, and I used the points in this answer to make the case. (I'd been *saying* semantics is better than mere formatting, but it sounded like just a philosophical argument without the points about accessibility and agent behavior.) (more) |
— | over 1 year ago |
| Comment | Post #286107 |
@#8176 that sounds like a good topic for a meta discussion. Would you like to start it? (I might not get to it for a couple days.) At current activity levels I don't think we'd need to spin off a separate community for it; whether it should be part of main Q&A or a separate category is something t... (more) |
— | over 1 year ago |
| Edit | Post #286107 | Initial revision | — | over 1 year ago |
| Answer | — |
A: Why was this question about authors shortening their sentences closed as a duplicate? The core of both questions is: why didn't these authors simplify complex sentence structures? It's hard to see how the answers would be significantly different for semicolons versus splitting into two sentences. I'm not sure "why did these authors do X?" is on-topic on Writing anyway (I can't rec... (more) |
— | over 1 year ago |
| Edit | Post #285027 | Initial revision | — | almost 2 years ago |
| Question | — |
How can we grow this community? Codidact's communities have a lot of great content that is helping people on the Internet. Our communities are small, though, and sustainable communities depend on having lots of active, engaged participants. The folks already here are doing good work; our challenge is to find more people like you ... (more) |
— | almost 2 years ago |
| Comment | Post #283746 |
What I meant is that instead of nuking the post without a trace, we could leave a "gravestone" behind to attach history to, like flags, if we wanted to. I haven't given this much thought. It just feels off that the reward for flagging spam is to lose "credit" for your flag in abilities calculations... (more) |
— | about 2 years ago |
| Comment | Post #283746 |
Yeah, sorry about that. I think when posts get completely obliterated, their associated stats go too. But flag count feeds into abilities, so we should see if we can do something about that. (more) |
— | about 2 years ago |
| Edit | Post #281759 |
Post edited: |
— | about 2 years ago |
| Edit | Post #283746 | Initial revision | — | about 2 years ago |
| Answer | — |
A: Flags page returns 500 error when having a flag on a deleted post This was a data error -- the post you flagged was spam, we do some extra stuff when nuking spam, and something went wrong. Fixed now. You won't see the post you flagged because it's completely gone, but you won't get an error page now either. (more) |
— | about 2 years ago |
| Comment | Post #281759 |
https://github.com/codidact/qpixel/issues/648 (more) |
— | about 2 years ago |
| Comment | Post #281759 |
@#53196 could you flag something that won't be deleted (like this post), to see if your flags page then shows up for you? (more) |
— | about 2 years ago |
| Comment | Post #283582 |
We actually are concerned about accessibility in our technical documentation, so thank you especially for pointing out the issue with screen readers and with CSS failing to load. The browser natively knows that the code tag is special and can do something with that absent any other inputs. (more) |
— | about 2 years ago |
| Comment | Post #283576 |
We apparently have that CSS already. My point is that we have two different ways of producing the same formatting in the output, the code *tag* and the code *CSS class*, and I'd like to know if there are reasons to prefer one over the other. I want us to have one consistent way of doing it, not two... (more) |
— | about 2 years ago |
| Edit | Post #283576 | Initial revision | — | about 2 years ago |
| Question | — |
HTML tags versus CSS classes: is one preferred over the other for the same styling? We publish documentation online using HTML. For things like fixed parameter names and other code literals, we use `` tags. My question is about styling these in tables. On our reference pages, we list parameters in tables -- parameter name in the first column, description in another. I have bee... (more) |
— | about 2 years ago |
| Comment | Post #282597 |
Even if we (optionally) collect an email address so that further interaction is possible, we'd still need a public ticketing system of some sort to manage it. (I mean "public" not just in the sense of where it lives but in the sense of "anybody can view tickets".) What tools should we consider for ... (more) |
— | about 2 years ago |
| Comment | Post #282596 |
Thanks for suggesting the "how can we improve this page?" framing; I agree that's much better. The context here (which I wasn't clear about) is technical documentation, not marketing fluff. One type of useful comment we get is requests for specific examples. Too many of our pages show only the bas... (more) |
— | about 2 years ago |
| Edit | Post #282589 | Initial revision | — | about 2 years ago |
| Question | — |
How can we integrate a lightweight public ticketing system into our documentation feedback form? We publish a substantial documentation set online. Each page has a place at the bottom that asks "was this helpful? (Y/N)", and if the person chooses "no" we offer a textbox. We collect all this feedback internally (it feeds into our internal ticketing system, except for the spam), but to the user,... (more) |
— | about 2 years ago |
| Edit | Post #26405 |
Post edited: updated link |
— | over 2 years ago |
| Edit | Post #282034 |
Post edited: |
— | over 2 years ago |
| Edit | Post #10919 |
Post edited: trying to fix tags |
— | over 2 years ago |
| Comment | Post #281759 |
I don't know, but I've forwarded this to someone who can take a closer look. (Gotta look the error code up in the database, which I can't do myself.) (more) |
— | over 2 years ago |
| Comment | Post #281759 |
Huh, weird. I see it too, for you here. (But not for me here. I haven't checked you elsewhere but I assume it's fine for me since it is for you.) (more) |
— | over 2 years ago |
| Edit | Post #281356 | Initial revision | — | over 2 years ago |
| Question | — |
In 2021, which publishers distribute novellas? The Hugo awards are prominent fan awards in the SF&F genre. In 2021, I noticed that all of the finalists in the Novella category are from a single publisher, Tor.com. Novellas have, I understand, historically been harder to market than either novels or short stories, though I don't know if that's c... (more) |
— | over 2 years ago |
| Edit | Post #281350 | Initial revision | — | over 2 years ago |
| Answer | — |
A: How do I brainstorm for writing positively about myself? Writing positively about yourself can be hard. It feels like bragging, which feels rude. What I've found helps is to frame it as a specific marketing project. It's not that I would go around boasting in general, but this year-end performance self-assessment is where I have to show my value and acc... (more) |
— | over 2 years ago |
| Edit | Post #25065 |
Post edited: updated link |
— | over 2 years ago |
| Edit | Post #35903 |
Post edited: updated link |
— | over 2 years ago |
| Edit | Post #37957 |
Post edited: assorted minor cleanup |
— | over 2 years ago |
| Edit | Post #279019 |
Post edited: |
— | over 2 years ago |
| Edit | Post #25900 |
Post edited: restored content that seems to have lost somewhere along the way |
— | over 2 years ago |
| Edit | Post #25901 |
Post edited: updated link |
— | over 2 years ago |
| Edit | Post #281003 | Initial revision | — | over 2 years ago |
| Answer | — |
A: How do we prevent Madcap Flare from injecting non-breaking spaces in our documentation? It turns out that "Global" doesn't mean global in Flare. We haven't figured out what it actually means, but to fix this you have to select "XML Editor" from the drop-down menu shown in the screen shot and then change it there. I changed it in both to be safe, and our team is no longer getting unw... (more) |
— | over 2 years ago |
| Comment | Post #281002 |
I beat my head against this for a while so when I finally found it I decided to ask and answer here. (more) |
— | over 2 years ago |
| Edit | Post #281002 | Initial revision | — | over 2 years ago |
| Question | — |
How do we prevent Madcap Flare from injecting non-breaking spaces in our documentation? We use Madcap Flare for our documentation, and it has an annoying property: if you happen to have the shift key down when you type a space, it inserts a non-breaking space (` `). Our documentation covers SQL, so things like `CREATE TABLE` are common and too often come out as `CREATE TABLE`... (more) |
— | over 2 years ago |
| Edit | Post #280765 | Initial revision | — | over 2 years ago |
| Answer | — |
A: How do we get Flare to stop modifying .gitignore? I received a response from Flare's technical support. There was a bug in Flare's git integration in some older versions (at least 2019r2; not sure how much farther back). This bug was fixed in Flare 2020, but the result is that if people are using mixed versions, as we are, then there's a tug of wa... (more) |
— | over 2 years ago |
| Edit | Post #280735 |
Post edited: |
— | over 2 years ago |
| Comment | Post #280721 |
File shares become write-only kitchen junk drawers, in my experience -- it's easy to add stuff but harder to find and organize it, and actually *maintaining* it is even harder. Jira would be an improvement for you because of the integration with Confluence, which you're already using. For example, ... (more) |
— | over 2 years ago |
| Edit | Post #280721 | Initial revision | — | over 2 years ago |
| Answer | — |
A: What are some ways to encourage team members to contribute and maintain a centralized wiki? There's no quick or complete fix, but the following things have worked for me. Plant the seeds early First, involve those new hires. When everything is new to them, you are in a better position to plant "culture" seeds. Maybe your old-timers have gotten used to not documenting anything, but t... (more) |
— | over 2 years ago |
| Edit | Post #26340 |
Post edited: |
— | over 2 years ago |
| Edit | Post #26342 | Post undeleted | — | over 2 years ago |
| Edit | Post #279019 |
Post edited: |
— | over 2 years ago |
| Edit | Post #279019 |
Post edited: |
— | over 2 years ago |
| Comment | Post #280651 |
@Olin thanks for the debugging tip! I hadn't thought of that. (more) |
— | over 2 years ago |
| Edit | Post #280651 |
Post edited: source-control is now the parent tag of git so don't need both (this question is specifically about git) |
— | over 2 years ago |
| Edit | Post #26346 |
Post edited: |
— | over 2 years ago |
| Edit | Post #31488 |
Post edited: |
— | over 2 years ago |
| Edit | Post #280651 | Initial revision | — | over 2 years ago |
| Question | — |
How do we get Flare to stop modifying .gitignore? We use Madcap Flare for our documentation, and the project is checked into git. (In case this matters, this is a locally-hosted git server, not GitHub.) The project uses a .gitignore file to avert commits of output files and assorted Flare byproducts that don't belong in source control. We do ... (more) |
— | over 2 years ago |
| Edit | Post #10747 |
Post edited: localized links |
— | over 2 years ago |
| Edit | Post #280515 | Initial revision | — | over 2 years ago |
| Answer | — |
A: Technical Writer Skill Set Some core skills for a technical writer are: - Ability to communicate effectively in writing. - Ability to understand the subject matter (what you're documenting) from the user's perspective, including the user's needs. - Ability to understand the subject matter enough to reason about its behavi... (more) |
— | over 2 years ago |
| Edit | Post #280477 | Question closed | — | over 2 years ago |
| Comment | Post #280477 |
Hello and welcome to Writing Codidact! This question is very broad so I'm putting it on hold for now. Can you edit to describe what problems you're running into? We're much better at solving specific problems than disseminating general hints. Every situation is a little different, so please tell ... (more) |
— | over 2 years ago |
| Comment | Post #279891 |
For feedback before submitting elsewhere for publication, need to consider that some publishers won't accept anything that's been "previously published". We can restrict visibility of a category to people with accounts to keep stuff out of Google, but it'd mean you wouldn't be able to usefully share... (more) |
— | almost 3 years ago |
| Edit | Post #279082 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #279085 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #28126 |
Post edited: updated link, integrated edit |
— | almost 3 years ago |
| Edit | Post #35035 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #35150 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #35578 |
Post edited: fixed link |
— | almost 3 years ago |
| Edit | Post #279085 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #279085 |
Post edited: |
— | almost 3 years ago |
| Comment | Post #279085 |
Oh right; there's a separate feature request about keyboard shortcuts for editing, not yet implemented. Sorry for my confusion. Could you file a bug report on any meta about the category issue @celtschk? Thanks. (more) |
— | almost 3 years ago |
| Comment | Post #279085 |
Oh whoops -- I thought we had a help topic about that, but I guess not. @celtschk see https://meta.codidact.com/questions/276697. (more) |
— | almost 3 years ago |
| Comment | Post #279085 |
True, and what I do normally anyway (just type the Markdown links) -- for me that's faster than going through a GUI, because I'm almost always inserting the links as I compose. But if somebody is using keyboard shortcuts to navigate the GUI, and that works in general but not in this specific case, t... (more) |
— | almost 3 years ago |
| Comment | Post #279078 |
Welcome back! It's good to see you here again. (more) |
— | almost 3 years ago |
| Edit | Post #279085 | Initial revision | — | almost 3 years ago |
| Answer | — |
A: Finishing link entry with enter sends the post instead That's a bug, yes. :-( Thanks for the report. As a workaround, if you choose[^1] the "insert" button instead of using "enter", it inserts the link into the markdown and puts you back in the editor. (I don't know if we have good-enough support for keyboard-only users to choose that button. If yo... (more) |
— | almost 3 years ago |
| Comment | Post #279079 |
Ooh, looking to the time *before* ubiquitous mice for hints -- nice! (more) |
— | almost 3 years ago |
| Edit | Post #278987 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #279019 |
Post edited: |
— | almost 3 years ago |
| Edit | Post #279019 | Initial revision | — | almost 3 years ago |
| Answer | — |
A: How can we revitalize our community? This suggestion grew out of a comment discussion on another answer. I'm posting it separately so it can be voted on. As discussed in other answers, straight copies of content from Somewhere Else are almost certainly hurting SEO and, in volume, can give a negative impression -- we look like a copy... (more) |
— | almost 3 years ago |
| Comment | Post #278987 |
@MarkBaker I agree with that assessment, but had previously perceived you to oppose deleting imported content. Thanks for clearing that up. Speaking for myself, I do have a few imported posts that I went on to *improve*, and I want to give them a new life here, but since I've claimed them they no l... (more) |
— | almost 3 years ago |
| Comment | Post #278987 |
@MarkBaker, are you suggesting we delete the imports (if we haven't improved them; I know some have been edited)? Not opposed, just asking for clarification. (more) |
— | almost 3 years ago |
| Edit | Post #278987 | Initial revision | — | almost 3 years ago |
| Answer | — |
A: How can we revitalize our community? I wonder if segregating content that was imported and not further improved would help. Create a new category, maybe called "Archive", and move there any post that hasn't had any modifications post-import. This means those of us who want to preserve our bodies of work can, but people visiting the Q&... (more) |
— | almost 3 years ago |
| Comment | Post #278891 |
We use italics for variables. In my first example, schema and table-name are variables and would be italicized, but "if not exists" is literal text that is optional. (We do try to include examples on all our reference pages too. We're trying to support both the "just show me the formal syntax" re... (more) |
— | almost 3 years ago |
| Edit | Post #278883 |
Post edited: switched gears on the first example halfway through and left bogus SQL; I realize it's just an example but still... |
— | almost 3 years ago |
| Edit | Post #278883 | Initial revision | — | almost 3 years ago |
| Question | — |
Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand? In our documentation of SQL functions and statements, we include a BNF-style syntax summary. As is conventional, we indicate optional elements in square brackets, like this: CREATE [IF NOT EXISTS] TABLE [schema.]table-name (column-definition[,...]) ... There's more to it, but that's the id... (more) |
— | almost 3 years ago |
| Edit | Post #278810 | Initial revision | — | almost 3 years ago |
| Question | — |
How can we revitalize our community? We've had low activity on our community for a while. Low activity means people visit less often, which means lower activity because they're not here asking and answering... iterate. We have ads active Somewhere Else, but without activity, people who follow them are unlikely to stick around. We s... (more) |
— | almost 3 years ago |
| Edit | Post #39319 |
Post edited: we've made some improvements since my last update |
— | almost 3 years ago |
| Edit | Post #5188 |
Post edited: |
— | almost 3 years 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 |
— | about 3 years 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 |
— | about 3 years ago |
| Edit | Post #278005 | Initial revision | — | about 3 years 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 3 years ago |
| Edit | Post #7374 |
Post edited: |
— | about 3 years 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) |
— | about 3 years 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) |
— | about 3 years 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) |
— | about 3 years ago |
| Edit | Post #277082 |
Post edited: |
— | about 3 years ago |
| Edit | Post #277082 | Initial revision | — | about 3 years 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) |
— | about 3 years ago |
| Comment | Post #276843 |
This is excellent. (more) |
— | about 3 years 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) |
— | about 3 years 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) |
— | about 3 years ago |
| Edit | Post #12577 |
Post edited: |
— | about 3 years ago |
| Edit | Post #5330 |
Post edited: |
— | about 3 years ago |
| Edit | Post #26400 |
Post edited: |
— | about 3 years ago |
| Edit | Post #10747 |
Post edited: |
— | about 3 years ago |
| Edit | Post #276451 | Initial revision | — | about 3 years 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) |
— | about 3 years 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) |
— | over 3 years ago |
| Edit | Post #276129 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39392 | Post edited | — | over 3 years ago |
| Edit | Post #275926 | Post edited | — | over 3 years ago |
| Edit | Post #39392 | Post edited | — | over 3 years ago |
| Edit | Post #39392 | Post edited | — | over 3 years ago |
| Edit | Post #275926 | Post edited | — | over 3 years ago |
| Edit | Post #275926 | Post edited | — | over 3 years ago |
| Edit | Post #275926 | Post edited | — | over 3 years ago |
| Edit | Post #275895 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #275876 |
Oh, that's bold? It's a small-enough difference that, on its own, I didn't realize. Thanks. (more) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #275819 |
Post edited: |
— | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #75027 |
@aCVn agreed on all points, including using sparingly. (more) |
— | over 3 years ago |
| Edit | Post #75027 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74997 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #74979 |
@Canina 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) |
— | over 3 years ago |
| Edit | Post #74979 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74968 |
Post edited: |
— | over 3 years ago |
| Edit | Post #7990 |
Post edited: trying to fix formatting of superscripts |
— | over 3 years ago |
| Edit | Post #10769 |
Post edited: I've since had the direct personal experience, so don't need this disclaimer now. |
— | over 3 years ago |
| Edit | Post #74968 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74906 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74875 |
Post edited: |
— | over 3 years ago |
| Edit | Post #74886 | Initial revision | — | over 3 years ago |
| Answer | — |
A: Sequence of Categories This is now configurable and I've moved Meta to the last position on this site. (more) |
— | over 3 years ago |
| Comment | Post #74877 |
This is a question about the site, not about writing, so we've moved it to Meta. (more) |
— | over 3 years ago |
| Edit | Post #74885 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #38585 |
Post edited: updated link |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74876 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #74875 |
Issue created: https://github.com/codidact/qpixel/issues/73 (a priority or sequence number is what I suggested too). (more) |
— | over 3 years ago |
| Comment | Post #74875 |
Ooh yes, we want the sequence to be controllable somehow. (more) |
— | over 3 years ago |
| Edit | Post #74857 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74846 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74844 |
Post edited: |
— | over 3 years ago |
| Edit | Post #74844 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74843 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39161 |
Post edited: |
— | over 3 years ago |
| Edit | Post #38868 |
Post edited: |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39190 | Question closed | — | over 3 years ago |
| Edit | Post #39190 |
Post edited: this doesn't appear to be about academic writing |
— | over 3 years ago |
| Edit | Post #74842 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #37593 | Question reopened | — | over 3 years ago |
| Edit | Post #38382 | Question reopened | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #23795 |
Post edited: updated link |
— | over 3 years ago |
| Edit | Post #74774 |
Post edited: |
— | over 3 years ago |
| Edit | Post #74769 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39219 |
Post edited: |
— | over 3 years ago |
| Comment | Post #74769 |
This is now fixed. (more) |
— | over 3 years ago |
| Edit | Post #74774 |
Post edited: |
— | over 3 years ago |
| Edit | Post #74774 |
Post edited: updated for new UI; categories are more discoverable now |
— | over 3 years ago |
| Edit | Post #39197 | Question reopened | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #74774 |
Post edited: |
— | over 3 years ago |
| Edit | Post #74774 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39575 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39219 |
Post edited: updated for change in strategy |
— | over 3 years ago |
| Edit | Post #39572 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #38434 |
Post edited: |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39559 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39549 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39522 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39525 |
Post edited: |
— | over 3 years ago |
| Comment | Post #39525 |
@xtal it got fixed between my post and your comment. I'll edit. (more) |
— | over 3 years ago |
| Edit | Post #39525 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #39524 |
Test comment to confirm bug report. Confirmed! (more) |
— | over 3 years ago |
| Edit | Post #39522 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39522 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39509 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39509 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39510 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39509 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39493 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #38520 | Question reopened | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #39408 |
Sounds like a great idea! (more) |
— | over 3 years ago |
| Edit | Post #38848 |
Post edited: |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39353 |
Post edited: Creating tag -- textbooks, being instructional and with assignments, are different enough to warrant a tag. |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39333 |
Post edited: I don't seem to know how to do footnotes here; <sup> doesn't seem to be it. |
— | over 3 years ago |
| Edit | Post #39332 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39333 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #15438 |
Post edited: |
— | over 3 years ago |
| Edit | Post #15436 |
Post edited: |
— | over 3 years ago |
| Edit | Post #15436 | Question reopened | — | over 3 years ago |
| Edit | Post #5186 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39328 | Initial revision | — | over 3 years 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) |
— | over 3 years 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. |
— | over 3 years ago |
| Edit | Post #39327 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #39321 |
That sounds good -- how often are people going to read more than 25 questions at a time anyway? (more) |
— | over 3 years ago |
| Edit | Post #39319 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39319 |
Post edited: can't make the markdown play well with the underscores in the name, so just removed it |
— | over 3 years ago |
| Edit | Post #39319 |
Post edited: |
— | over 3 years ago |
| Edit | Post #39319 | Initial revision | — | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39318 | Initial revision | — | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Comment | Post #39311 |
Sorry about that @Mark; I meant the text at the link I posted is for Codidact, not specifically Writing. (more) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39215 |
Post edited: |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years ago |
| Edit | Post #39305 |
Post edited: |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | over 3 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #35532 |
Post edited: |
— | almost 4 years 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) |
— | almost 4 years ago |
| Comment | Post #34684 |
Related: https://writing.codidact.com/questions/35006 (more) |
— | almost 4 years ago |
| Comment | Post #35006 |
Related, on telepathy: <a href="https://writing.codidact.com/questions/34684">https://writing.codidact.com/questions/34684</a>. (more) |
— | almost 4 years ago |
| Edit | Post #39275 |
Post edited: added suggestion from comment |
— | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #39275 |
Post edited: |
— | almost 4 years ago |
| Edit | Post #39275 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #39219 |
Post edited: |
— | almost 4 years 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) |
— | almost 4 years ago |
| Comment | Post #39267 |
Heh. :-) (And if I'd checked chat before posting this I'd've known that. Sorry.) (more) |
— | almost 4 years ago |
| Edit | Post #39266 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #10921 |
Post edited: added link for the open-source tool (people already know how to find Visio) |
— | almost 4 years ago |
| Edit | Post #39257 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #34684 | Question reopened | — | almost 4 years ago |
| Edit | Post #39248 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #39247 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #39246 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #39245 | Initial revision | — | almost 4 years 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) |
— | almost 4 years ago |
| Comment | Post #39233 |
Yes, meta questions should appear (we want people to notice and come to meta), but labeled. (more) |
— | almost 4 years ago |
| Comment | Post #39219 |
Great to see everyone here! (more) |
— | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #26048 | Post edited | — | almost 4 years ago |
| Edit | Post #25899 | Post edited | — | almost 4 years ago |
| Edit | Post #27469 | Post edited | — | almost 4 years ago |
| Edit | Post #36928 | Post edited | — | almost 4 years ago |
| Edit | Post #39226 | Initial revision | — | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years 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) |
— | almost 4 years ago |
| Edit | Post #25663 | Post edited | — | almost 4 years ago |
| Edit | Post #33955 | Post edited | — | almost 4 years ago |
| Comment | Post #39219 |
Welcome @Neil! (I don't know if we have comment pings yet.) (more) |
— | almost 4 years ago |
| Edit | Post #39219 | Initial revision | — | almost 4 years 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) |
— | almost 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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) |
— | about 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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 4 years 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) |
— | over 4 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 5 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 5 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 5 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 5 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) |
— | almost 5 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 5 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 5 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) |
— | about 5 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 5 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 5 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 5 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 5 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 5 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 5 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 5 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 5 years ago |
| Answer | — |
A: What are the benefits of including complete working code samples in documentation There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes too simple (simplistic), but this example sh... (more) |
— | over 5 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 5 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 5 years ago |
| Answer | — |
A: How do I write a report analyzing a system's weaknesses and how to address them? I've done this sort of thing as part of evaluating technologies. It's usually cast as an evaluation, covering both benefits and weaknesses, rather than just weaknesses. I suggest getting clarification on whether to address benefits too. The purpose of such a document is to help people make informe... (more) |
— | over 5 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 5 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 5 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 5 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 5 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 5 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 5 years ago |
| Answer | — |
A: What will be the copyright situation if I self-publish an anthology of my unpublished short stories? If you live in one of the 175 countries that are signatories to the Berne Convention, then your work is automatically copyrighted when you create it. Registration is not required to have copyright to your work. There are still advantages to registration in some countries. In the US, for example, you... (more) |
— | over 5 years ago |
| Answer | — |
A: Single author scientific paper, 'we' or 'I'? The convention in scientific writing, at least in the hard sciences, is to avoid "I" even for single-author papers. I suspect (but can't prove) that this is why you see so much passive voice in such papers ("the doohickey was then frobitzed to induce a somethingorother reaction"). According to this ... (more) |
— | over 5 years ago |
| Answer | — |
A: How to write a scientific journal? In your question you talk about writing "a scietific journal" (to track your progress), but then you talk about publishing in industry journals. Those are not the same thing -- and when you submit to other journals you will have to edit to meet their standards (which vary). Instead, think about the ... (more) |
— | over 5 years ago |
| Answer | — |
A: Is Wikipedia Trustworthy? Wikipedia is a crowd-sourced site where anybody can contribute, just like this one. Wikipedia strives for verifiability and neutrality and has an active user community, but that doesn't mean that things can't get past it. It doesn't mean information there can't be wrong. Some pages are full of detail... (more) |
— | over 5 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 6 years ago |
| Answer | — |
A: How should I start to write a flash fiction story? Flash fiction gives you very little leeway. 100 words won't allow for extended plot, character development, scene-setting... really, it's enough for one scene. I've seen people pull off more in that wordcount, but it's hard and you're a beginner. Imagine one scene that is interesting enough to write... (more) |
— | almost 6 years ago |
| Answer | — |
A: How would you cite your own figure in MLA? If the figure were in another published work, you would cite it the same way you would if it were somebody else's work. Citing yourself is done when applicable; that's not an error. You indicated in a comment, however, that you drew the figure for the purpose of the present work. In that case, you j... (more) |
— | almost 6 years ago |
| Answer | — |
A: Citing Oracle documentations of Java The general format for a reference citation in Harvard style is: > Last name, First Initial. (Year published). Title. City: Publisher, Page(s). For a web site, this guide gives the following format: > Last name, First initial (Year published). Page title. [online] Website name. Available at: URL [... (more) |
— | almost 6 years ago |
| Answer | — |
A: Do I always need to use linkers and connectors? Use transitional phrases when you need to clarify or highlight a connection. Especially in technical writing (where concise is better), don't use them just to use them. In your example, the second and third statements follow logically from the first -- you believe that data should be accessible, whi... (more) |
— | almost 6 years ago |
| Answer | — |
A: Scientific article: How to say that with our result something could be done but hasn't I don't have citations, but I've seen a couple approaches to this problem: - "One possible application of (this work) would be to..." -- by casting it speculatively like that, using "would be", you're saying "this is an idea, not something we've demonstrated". - "A possible application of (this wor... (more) |
— | almost 6 years ago |
| Answer | — |
A: Indexing: after or during the writing process I've done it both ways, and have found that a hybrid approach ends up working best. Doing it at the end means you can focus just on indexing (not writing). You're more likely to be consistent in choice of terms, avoiding unintended synonyms where some entries are under term A and some are under term... (more) |
— | almost 6 years ago |
| Answer | — |
A: How does one cite a print chapter in a textbook without the exact page? A general principle of citation is: only cite what you actually used. You haven't seen the original work, so don't cite it based on someone else's quote. What if the quote you're working from is wrong? Citing the original in that case would misinform people who don't know the truth or appear sloppy t... (more) |
— | almost 6 years ago |
| Question | — |
In searchable documentation, what function does a glossary serve? I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google). The doc set has a glossary, which predates most team members and has accumulated a lot of entries over time. It currently contains the followi... (more) |
— | about 6 years ago |
| Answer | — |
A: How can we make compiling release notes less chaotic? I'm at a different company now than I was when I asked this question, but the new one had the release-notes problem too. Here is how we solved it (at doc's instigation): - When a bug is filed, if it's customer-reported or customer-facing, the "needs release note" box is checked. (There is a triage t... (more) |
— | about 6 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) |
— | about 6 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) |
— | about 6 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) |
— | about 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 years ago |
| Answer | — |
A: How to present details about the setting in a fantasy world without telling? The people in your story might not know anything about Earth, but your readers do. You can show lighter gravity by describing things that couldn't happen on Earth -- a person out for a jog bounding high enough to brush tree branches, somebody casually carrying an anvil under one arm (this depends on ... (more) |
— | over 6 years ago |
| Answer | — |
A: How do I handle a backstory big enough to be a story of its own? The questions you need to answer are: 1. What story do I want to tell? 2. What elements do I need to have available to tell it? If you want to tell your backstory, and it stands alone, then you have the first book of a series, with the second book picking up some time later. This is a common appro... (more) |
— | over 6 years ago |
| Answer | — |
A: How do I decide whether to answer questions, or leave them unexplained? You don't need to -- and shouldn't try to -- explain every detail of every bit of background you've come up with. If your writing says "I had to do lots of research to write this so I'm going to make you read it", it's getting in the way of the story. However, you need to address anything that's rea... (more) |
— | over 6 years ago |
| Answer | — |
A: Why are names in fantasy novels often "original"? As others have said, most fantasy is set in a different environment, where the non-English-speaking inhabitants have different cultural and linguistic norms. So it's only natural to want to convey that. But I think there's another reason. If I name my characters "Bob" or "Pocahantus" or "Chun Li", y... (more) |
— | over 6 years ago |
| Answer | — |
A: When to introduce a list of two with the word "both" "Both" can act as emphasis when one of the two is unexpected. In this usage, the unexpected one is placed second. For example, consider the difference between: > Tom and his manager thought the customer complaint was invalid. and > Both Tom and his manager thought the customer complaint was invali... (more) |
— | over 6 years ago |
| Answer | — |
A: Can I Have My Own Website Separate of My Publisher? The nice thing about websites is that there can be more than one. Publishers, being publishers, want to promote their books, which will of course include on the web, but that doesn't mean you can't. Subject to the terms of any specific contract, and the specific promotional language/messaging they wa... (more) |
— | over 6 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 7 years ago |
| Answer | — |
A: Writing a story with 10 POV characters (about a reality game show) It sounds like you're describing an ensemble cast, where there are several key characters but no single main character. While the page I linked to talks about TV/movies, the same applies to written works. The style is not at all uncommon in, at least, science-fiction novels (what I mostly read). To ... (more) |
— | almost 7 years ago |
| Question | — |
Can we use MadCap Flare with semantic markup? My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions (for variables, admonitions, snippets, and so on). We use CSS to style the HTML to our tastes. We use the build tool that comes with Flare to produce th... (more) |
— | almost 7 years ago |
| Answer | — |
A: How to better imply time and place changes? One way to convey time is with signposts: > She buried her head in the pillow as she smacked the alarm clock for the third time. > > He fumbled with his key in the lock, glowering at the burnt-out porch light. "Gotta remember to fix that before leaving for work tomorrow," he muttered. > > Over din... (more) |
— | almost 7 years ago |
| Answer | — |
A: Where can I find a market for "offbeat" short stories about God's relationship with us? Speculative stories about God, or gods, can show up in the realm of speculative fiction, science fiction, or fantasy. Consider the following examples: - Some of the stories in Wandering Stars, ed. Jack Dann - Larry Niven's version of the Inferno trilogy - Mark Twain's Letters from the Earth - Isaac ... (more) |
— | almost 7 years ago |
| Answer | — |
A: How to keep documents with example full date timeless You are concerned that a document containing a recent, past date (like from last year) will make readers think your document is out of date. One way to address that is to use dates that are obviously not recent -- Jan 1 1970, Dec 31 2037, etc. If you have a section in the frontmatter about document ... (more) |
— | almost 7 years ago |
| Answer | — |
A: Can I use a phrase from song lyrics as the title of my book? Short phrases like that can't usually be copyrighted. The link is from the US government, but I believe it to be the same for most of the Berne Convention countries. Of course you should consult your local law on this. In this specific case, there's already a TV show by that name), so they apparentl... (more) |
— | about 7 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 7 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 7 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 7 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 7 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 7 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 7 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 7 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 7 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 7 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 8 years ago |
| Answer | — |
A: Is it acceptable to ask a question in an argumentative paper? This is a rhetorical question and, used well, can enhance the essay. The key to using this device is to first raise a question, issue, or concern that the reader might reasonably have, and then to address it. You are, essentially, putting a question in the "mouth" of your reader so that you can go on... (more) |
— | almost 8 years ago |
| Answer | — |
A: How I should handle gender-neutral pronouns in technical writing? Using "he/she" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people. What I do is to write around the problem wherever possible. First off, if you're referring to the user of your API, it's better to write in secon... (more) |
— | almost 8 years ago |
| Answer | — |
A: Two perspectives in a non-fiction book One approach is to write separate chapters (maybe alternating, but maybe in this case more from her?) with the writer identified at the beginning of each. A similar approach was taken in the Jumper novels by Stephen Gould; each chapter is "titled" with the name of the point-of-view character for that... (more) |
— | almost 8 years ago |
| Question | — |
Maintaining readers over time with serialized fiction? I am one of several authors on a fairly new shared blog. The blog has a mix of serialized and one-shot posts. Because it's a new blog (2.5 months, 30 posts so far), there is quite a variety of posts and authors (though all on the broader theme for the blog) and we're not yet at the point where author... (more) |
— | almost 8 years ago |
| Answer | — |
A: Is it necessary to explain what is written in upcoming chapters? First, if your institution has a style guide, follow its recommendations if there are any. But assuming it is silent on this point or you don't have one: It's helpful to provide an outline of the rest of the report. If you have a table of contents already that might be good enough (I've seen TRs wit... (more) |
— | almost 8 years ago |
| Answer | — |
A: Should I put diagrams into a formal essay? There are a few relevant factors: Use diagrams when they add value I see plenty of formal writing that includes diagrams -- technical flow diagrams, trend graphs, timelines, resource-allocation charts, and more. The main question you should be asking yourself is: does this diagram add value? Does i... (more) |
— | almost 8 years ago |
| Answer | — |
A: How can I convey something without going into details? You can imply rather than say things with descriptions. For example: > He picked his way down the garbage-strewn street, stepping aside to yield to an over-sized rat. The reek of stale beer and body odor assaulted his nostrils. He averted his eyes as he passed alleys; no good could come of that. It ... (more) |
— | almost 8 years ago |
| Answer | — |
A: Format keyboard keys in documents I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of ... (more) |
— | almost 8 years ago |
| Answer | — |
A: How long is too long for a blog post? A longer post can work on a blog that usually tends toward shorter posts if you take some care in structuring it. "Here are 20,000 words, plus equations" may send some people to the "back" button right off, but a five-minute introduction followed by an expansion can satisfy both audiences -- those lo... (more) |
— | almost 8 years ago |
| Answer | — |
A: How to cite nonpersonal email "Private" doesn't mean just one recipient; it just means "not public". When you throw a by-invitation party in your home it's a private affair even if there are 50 people there. Email is the same way. The bigger problem here is that the person you're citing didn't write directly to you. So if you ci... (more) |
— | almost 8 years ago |
| Answer | — |
A: How to work on a new software feature that affects different topics It depends, but probably you want the distributed approach where the chapter on X tells you everything you need to know about X, even if some of that is only relevant if you're using feature Y. However, if Y is a corner case or involves a lot of changes to several other features, you might be better ... (more) |
— | almost 8 years ago |
| Answer | — |
A: How do I get rid of the tic of paired adjectives, predicates, etc.? When I'm editing technical documentation (and, ideally, when I'm writing it in the first place), I try to make every word earn its place. If both words in your phrases need to be there to make your point, then don't worry about it -- that's not a tic but the writing process. In the case of pairs (or... (more) |
— | about 8 years ago |
| Answer | — |
A: What do I put on my copyright page when self-publishing? If you're self-publishing and not doing it through a company, use your real name: "Copyright (C) 2015 John Doe". Under the Berne Convention (which applies in most countries), you own the copyright from the moment of creation until you assign it away. You have no need to assign it away, so you don't n... (more) |
— | about 8 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) |
— | about 8 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) |
— | about 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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 8 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) |
— | over 8 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) |
— | over 8 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) |
— | over 8 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) |
— | over 8 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) |
— | over 8 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) |
— | over 8 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 9 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 9 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 9 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) |
— | almost 9 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) |
— | almost 9 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) |
— | almost 9 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) |
— | almost 9 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) |
— | almost 9 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 9 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 9 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 9 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 9 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... (more) |
— | about 9 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 9 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 9 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) |
— | about 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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 9 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) |
— | over 9 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) |
— | over 9 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) |
— | over 9 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) |
— | over 9 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) |
— | over 9 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 10 years ago |
| Answer | — |
A: Using capital letters for shouting Text in all capitals is harder to read than text in mixed case: > A 1955 study by Miles Tinker showed that “all-capital text retarded speed of reading from 9.5 to 19.0 per cent for the 5 and 10-minute time limits, and 13.9 per cent for the whole 20-minute period.” Tinker concluded that, “Obviously, ... (more) |
— | almost 10 years ago |
| Answer | — |
A: How do I write for webcomics? A comic -- web or paper, cartoon strip or sophisticated graphic novel -- is a different medium from conventional written stories. The biggest difference is that it's hard to do exposition; those long explanatory passages that you could slip into a novel don't fit into a few panels. It's also hard to ... (more) |
— | almost 10 years ago |
| Question | — |
How do I avoid tech/social errors in near-future fiction? Not long ago I read a novel set in the near future (mid-21st century). My suspension of disbelief was totally fine with time travel, an implanted "universal translator" of sorts, major medical advances... but balked at plot points that depended on people being limited to land-lines (no mobile communi... (more) |
— | almost 10 years ago |
| Answer | — |
A: Is my serial-killer novel horror or crime? I agree with SF and Lauren that who your POV character is affects this. But I'll take a different approach in answering this: when you talk about your project socially (e.g. with friends/family), what do you tend to focus on? What's exciting about this to you? When you're not worried about making a g... (more) |
— | almost 10 years ago |
| Answer | — |
A: How can I prevent, or work around, unfortunate hyphenation in critical words? With help from a coworker I was able to fix this by adding the following to the FO stylesheet: And likewise for other elements that should get this treatment, like `methodname` and `literal`. This creates a wrapper around the native style, changing hyphenation only... (more) |
— | almost 10 years ago |
| Question | — |
How can I prevent, or work around, unfortunate hyphenation in critical words? In technical documentation, sometimes the tool's automatic hyphenation makes a bad break in the middle of a term, like the name of an environment variable or function. In these cases I would rather have a short line than hyphenation, though I want hyphenation in the document in general. I can try to ... (more) |
— | almost 10 years ago |
| Answer | — |
A: becoming better blogger when I write about diverse topics In my experience there are two main types of blogs out there, topic-focused and person-focused. You're describing the latter. Person-focused blogs, which cover a range of topics and styles with the unifying theme of "interesting enough for the blog author to want to write about", seem to attract a s... (more) |
— | almost 10 years ago |
| Answer | — |
A: Really Stuck: Writing Dialogue If your antagonist is living in the present time (but is 1000 years old), then is there any reason to believe that his speech hasn't evolved? Think about what happens to people when they move to a new place with language patterns different from the ones they grew up with; don't they tend to adapt? T... (more) |
— | about 10 years ago |
| Answer | — |
A: Punctuating Thoughts "Hard and fast rules" come from the style guide you're following; all else is convention. I've seen both styles in fiction, so to decide which to use you can look at examples of similar type (genre, length, etc) to see what they do. If you're submitting for publication, then the publisher might have... (more) |
— | about 10 years ago |
| Answer | — |
A: Background speech with foreground dialogue I saw an effective example of this in 1634: The Baltic War (David Weber & Eric Flint) recently. The factors that made it work were: - The background speech was in italics (as you've done here). - The passages of background speech began and ended in the middle of sentences. - There wasn't a lot of ... (more) |
— | about 10 years ago |
| Answer | — |
A: Describing common hand gestures In many cases you don't actually need, or necessarily want, to describe the gesture itself. It is often enough, or even preferable, to (a) convey that there was a gesture and (b) convey its meaning, without describing the gesture. There are at least two reasons for this: 1. The gesture is idiomatic ... (more) |
— | about 10 years ago |
| Question | — |
API reference doc: best practices for describing opaque parameters? The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool is Javadoc. One property of such generated documentation is that the code interfaces -- for example,... (more) |
— | about 10 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) |
— | about 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 10 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 11 years ago |
| Answer | — |
A: Writing a programming book: how to present directory structures I do something similar to your ASCII implementation, but instead of an ASCII block I use compact bulleted lists (with sub-lists). File/directory names are still styled as they would be in running text. In addition to conveying the structure, this also gives me a handy place to add explanations where ... (more) |
— | about 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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 11 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) |
— | over 11 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 12 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 12 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 12 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 12 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 12 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 12 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 12 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 12 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 12 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) |
— | about 12 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 12 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 12 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 12 years ago |