Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

General Q&A about the craft of professional writing, editing, and publishing. Questions about all types of writing are welcome -- fiction, technical documentation, scholarly articles, poetry, scriptwriting, blogs, and more.

Filters (None)
81%
+7 −0
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 general...

4 answers  ·  posted 4y ago by Monica Cellio‭  ·  edited 3y ago by Canina‭

71%
+3 −0
What can a novel do that film and TV cannot?

I have enjoyed writing prose for years and have a few short stories penned. I would like to build up to a novel but believe I have identified a potential weakness in my storytelling. My style is g...

5 answers  ·  posted 5y ago by Smeato‭  ·  edited 3y ago by Canina‭

50%
+0 −0
What content parts should a technical (IT) CV have?

I've been struggling for a while with my CV and I need help on deciding which sections should I include in it? I lack the formatting skill, I remember studying in school how to prepare my CV - ther...

1 answer  ·  posted 12y ago by karla‭  ·  edited 3y ago by Canina‭

60%
+1 −0
Text Editors. Suggesting & Tracking Changes to Plain-Text Documents

Many word processors are capable to tracking and displaying changes made to a document. Those changes are typically displayed in special markup supported by the editor. E.g. But when using a pla...

5 answers  ·  posted 11y ago by Robert Cartaino‭  ·  last activity 3y ago by celtschk‭

60%
+1 −0
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 underst...

2 answers  ·  posted 3y ago by Monica Cellio‭  ·  last activity 3y ago by Mark Baker‭

71%
+3 −0
How do I brainstorm for writing positively about myself?

I've always struggled writing about myself, but I need to apply for a program and the application has a lot of very broad but personal questions like, Tell us why you would be a good leader Exp...

2 answers  ·  posted 3y ago by Sigma‭  ·  last activity 3y ago by Monica Cellio‭

60%
+1 −0
Is Wikipedia Trustworthy?

So in elementary school, I was told not to use Wikipedia too much because you can't trust what they write. So then for all the projects, I used the Canadian Encyclopedia, but then now, I really wou...

5 answers  ·  posted 6y ago by iiRosie1‭  ·  last activity 3y ago by Monica Cellio‭

60%
+1 −0
Is there a need for better software for writers?

Software developers don't ever work in text editors, instead they use IDEs (integrated development environments) full of code assistance tools, etc. Why don't writers use similarly advanced writin...

4 answers  ·  posted 5y ago by mauleros‭  ·  last activity 3y ago by Monica Cellio‭

50%
+0 −0
Compelling story with the world as a villain

My main character is up against the world, or, rather, the world and reality are up against her. A good story is in some ways defined by its villain. 1984 personifies its villain by adding a repr...

5 answers  ·  posted 5y ago by Calypso Writes‭  ·  last activity 3y ago by Monica Cellio‭

60%
+1 −0
How would you pop the reference to a minor case into the ‘Application' section of an essay?

I don't understand the example emboldened below. Can't you add just a superscript number in the text, then in the footnotes cite that "minor case"? Unquestionably one superscript cannot "detract fr...

0 answers  ·  posted 3y ago by TextKit‭

law
60%
+1 −0
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 aver...

1 answer  ·  posted 3y ago by Monica Cellio‭  ·  last activity 3y ago by Monica Cellio‭

71%
+3 −0
Does DRY (Don't Repeat Yourself) Apply to Documentation?

In programming, it's usually accepted that DRY code is better code in most situations. Does this principle also apply to documentation? I'm asking about the documentation output, not necessarily ...

3 answers  ·  posted 6y ago by Scribblemacher‭  ·  last activity 3y ago by Lundin‭

66%
+2 −0
What are some ways to encourage team members to contribute and maintain a centralized wiki?

I joined my current company and department a few years ago. We had some documentation for processes but most people had been around for a long time and never needed it, so it was very sparse. Sinc...

3 answers  ·  posted 3y ago by Sigma‭  ·  last activity 3y ago by Mark Baker‭

66%
+2 −0
Linking documentation to Git commit comments

Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a forma...

1 answer  ·  posted 6y ago by Gypsy Spellweaver‭  ·  edited 3y ago by Monica Cellio‭

60%
+1 −0
Git plugins for MS Word?

Is anyone aware of a plugin for MS Word that allows me to keep my documents in a git repository (gitlab compatibility would be even better)? I'm aware that git diffs won't be very meaningful, merge...

0 answers  ·  posted 5y ago by Kurt Weber‭  ·  edited 3y ago by Monica Cellio‭

75%
+4 −0
Good Examples of and Practices in Code Documentation

I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents is to imbibe good examples. Can you recommend any exam...

1 answer  ·  posted 10y ago by Stefan Piskorski‭  ·  edited 3y ago by Monica Cellio‭

50%
+0 −0
Help! Editing Tips? [closed]

Hey, I'm having trouble editing my book. I have a crime novella but I can't edit that well. Does anyone have any tips to help? Thanks! ~Rosewood

0 answers  ·  posted 3y ago by Rosewood‭  ·  closed 3y ago by Monica Cellio‭

71%
+3 −0
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]...

4 answers  ·  posted 3y ago by Monica Cellio‭  ·  last activity 3y ago by Derek Elkins‭

71%
+3 −0
How to make the reader think that the *character's* logic is flawed instead of the author's?

Following up on my previous question, "How to make the villain's motives understandable if his logic is flawed?", how can I let the reader know that the lack of logic is on the character's side, in...

9 answers  ·  posted 6y ago by Yuuza‭  ·  edited 3y ago by Monica Cellio‭

60%
+1 −0
Time measures in fantasy worlds

I wonder, what could be a good way to provide time measures in a fantasy universe. I don't mean the calendar which is covered in the question: Out of this world... Giving it time?, but measures lik...

5 answers  ·  posted 11y ago by Darek Wędrychowski‭  ·  edited 3y ago by Canina‭

50%
+0 −0
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...

0 answers  ·  posted 5y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

60%
+1 −0
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 translat...

1 answer  ·  posted 5y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

66%
+2 −0
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 ...

2 answers  ·  posted 5y ago by Monica Cellio‭  ·  last activity 3y ago by Monica Cellio‭

83%
+8 −0
How do you avoid the problem of a collaborative work having separate voices?

I've not done collaborative writing before, but I've read several works, and sometimes the text strikes me as having a split personality: some parts were clearly written by one author, while others...

3 answers  ·  posted 12y ago by Craig Sefton‭  ·  last activity 3y ago by Monica Cellio‭

77%
+5 −0
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?

I was putting together an instruction page (for setting up a game that my business created), which included a whole lot of various pointers, most of which were only a sentence or two long. These ex...

3 answers  ·  posted 4y ago by Mithical‭  ·  last activity 4y ago by Mark Baker‭

66%
+2 −0
How to determine relative success of different, similar books published by different means?

This answer discusses how to choose between traditional print publishing, ebook publishing, self publishing, etc., and concludes by stating that You should publish your book using the channel wher...

1 answer  ·  posted 4y ago by Canina‭  ·  last activity 4y ago by msh210‭

66%
+2 −0
What is the main publishing format authors should be using today?

I've recently begun investigating the publishing process, and what I as an author need to do to get my book read. I'm aware of the self-publishing option, but as I have not studied any options exte...

1 answer  ·  posted 4y ago by Thomas Myron‭  ·  last activity 4y ago by Mark Baker‭

75%
+4 −0
Which parts of a character's plan should be revealed beforehand?

Two characters (one is a PoV character) come up with a plan to break a third out of prison. They succeed, with only minor complications. If I describe too many details of their plan beforehand, it ...

2 answers  ·  posted 4y ago by Evil Sparrow‭  ·  last activity 4y ago by Razetime‭

66%
+2 −0
Getting details of a past century right

I have been gathering ideas for a novel. The basic idea is in place; the story combines two different eras but the same place. How do I get the little details about the place, the people, their lif...

4 answers  ·  posted 11y ago by Kuchiki Byakuya‭  ·  last activity 4y ago by Monica Cellio‭

77%
+5 −0
How to ask for permission to use readers' endorsements?

I have a blog with long, analytic articles. Because of their nature, they don't really attract much clicks. However, once people distill it thoroughly, many of them express that the articles are in...

1 answer  ·  posted 4y ago by Ooker‭  ·  last activity 4y ago by Mark Baker‭

71%
+3 −0
At what point does a POV character noting their surroundings go from showing/telling to an infodump?

In a story I'm working on, at one point one of the main characters (also the POV character in this case) arrives at a new location which he has never been in before. This is the first mention of th...

7 answers  ·  posted 6y ago by Canina‭  ·  last activity 4y ago by Mark Baker‭

66%
+2 −0
How to keep track of worthwhile snippets from discovery writing, which don't work where they were first written?

Sometimes, when I write, I find myself writing down a path that ends up not leading at all where I wanted to go with what I was writing. That's to be expected when discovery-writing. Depending on t...

1 answer  ·  posted 4y ago by Canina‭  ·  last activity 4y ago by Mark Baker‭

66%
+2 −0
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 pl...

1 answer  ·  posted 4y ago by Monica Cellio‭  ·  last activity 4y ago by manassehkatz‭

66%
+2 −0
How to structure a sentence containing long code examples?

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sente...

4 answers  ·  posted 9y ago by Dave Jones‭  ·  edited 4y ago by Monica Cellio‭

60%
+1 −0
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 ...

4 answers  ·  posted 12y ago by Monica Cellio‭  ·  edited 4y ago by Monica Cellio‭

66%
+2 −0
How to train readers in Argot or Slang

I have a character which is typical street thug, criminal and did his time in jail. He is using a lot of underground Argot and thug slang. Example below At the end we got the ice, gravy train if y...

1 answer  ·  posted 4y ago by Prahara‭  ·  last activity 4y ago by Canina‭

84%
+9 −0
Is writing policy pages in a lighthearted manner harmful in any way?

Recently, I threw together a draft of a policy page about promotional content, with some guidelines on what to keep in mind to avoid spamming. (Incidentally, this is for Codidact itself.) I decided...

2 answers  ·  posted 4y ago by Mithical‭  ·  last activity 4y ago by Mark Baker‭

77%
+5 −0
Everyone's a woman: how do you show that through gender-neutral language?

In my latest short story I'm playing around with common gender misconceptions. It's set in a near future society were men have disappeared, and all roles are taken up by women. The theme is played ...

1 answer  ·  posted 4y ago by Liquid‭  ·  last activity 4y ago by Prahara‭

71%
+3 −0
Dealing with Audience's expectations

Over the years I gained small audience and I love them. My last work quite disappoint them in regard of one character and I feel bad about it. I felt like character's struggle she went through woul...

2 answers  ·  posted 4y ago by Prahara‭  ·  last activity 4y ago by Liquid‭

75%
+4 −0
Writing "light hearted" lead characters

For some reason, when I find myself writing a male protagonist, I seem to default to the brooding, gritty kind of man that could easily find his place into a noir novel. Those characters are often ...

2 answers  ·  posted 4y ago by Liquid‭  ·  last activity 4y ago by Prahara‭

75%
+4 −0
Action scene pacing and clarity

I am using, for action scenes, this three act format which allows me to control pacing and create order in hectic environment: Action - analysis - reaction Johann fired (action) his pistol and mi...

1 answer  ·  posted 4y ago by Prahara‭  ·  last activity 4y ago by Mark Baker‭

66%
+2 −0
In a young adult, what would cause development of a high sense of duty?

This is a question related to my previous question about child's morality, but different criteria are applied. Criteria and Question: My desired kid would be born commoner but from merchant class, ...

2 answers  ·  posted 4y ago by Prahara‭  ·  last activity 4y ago by gymbrall‭

71%
+3 −0
Could a 13-year-old have morality to disagree with their family's unethical business practices, while those are the norm in their society?

I am very bad at writing children characters in my stories, I always make them either too "dumb" or too developed. Currently I am in need of believable child +- 13, boy or girl. Requirements: My de...

2 answers  ·  posted 4y ago by Prahara‭  ·  last activity 4y ago by Monica Cellio‭

84%
+9 −0
How can I pinpoint a story's moral dilemma?

In this answer, Mark Baker makes a statement about story: All story ideas are basically a variation on one thing. A man (or woman, or child, or small furry animal) has two desires, both of which h...

4 answers  ·  posted 4y ago by icanfathom‭  ·  last activity 4y ago by DPT‭

80%
+6 −0
"The tale how" vs. "The tale of how"

My SO and I were discussing the following sentence in his writing: This is the tale how once the Septemi helped King Nicodemus subdue walking firestorms, how we hunted cultists and mongrelfolk i...

2 answers  ·  posted 4y ago by Sigma‭  ·  last activity 4y ago by xtal‭

75%
+4 −0
Telephone Conversations

The Situation: I am writing a short story. My POV character is listening to another person having a telephone conversation. The POV character only hears the one person speaking and not the response...

3 answers  ·  posted 5y ago by Walter Sanville‭  ·  last activity 4y ago by Prahara‭

75%
+4 −0
How do I approach rewriting an entire user guide in an agile environment?

I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The ...

2 answers  ·  posted 10y ago by john_doe‭  ·  last activity 4y ago by Secespitus‭

66%
+2 −0
Is page range inclusive or exclusive?

When writing a bibliography entry, if I want to cite pages 1 up to 10, including both 1 and 10 (i.e., 1, 2, 3, 4, 5, 6, 7, 8, 9, and 10) should I write 1-10 or 1-11?

3 answers  ·  posted 5y ago by Terry Price‭  ·  last activity 4y ago by manassehkatz‭

71%
+3 −0
Chapter 1 Problems

I've written for a year now(ish) and I've come along some great ideas I'd like to form into existence. But I always, always, ALWAYS have one problem. I can't seem to get past the first chapter or...

6 answers  ·  posted 6y ago by A.N.M‭  ·  last activity 4y ago by Prahara‭

75%
+4 −0
How to show powerful emotion in a character trying to hide it?

This question deals with showing the emotions of characters when those characters are actively trying to hide their emotions. If the emotion is something subtle, like apprehension or annoyance, you...

3 answers  ·  posted 4y ago by Thomas Myron‭  ·  last activity 4y ago by Prahara‭