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)
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...
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 ...
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...
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...
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...
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...
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
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]...
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...
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...
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...
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...
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 ...
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...
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...
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...
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...
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 ...
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...
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...
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...
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...
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...
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...
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 ...
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...
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...
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 ...
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...
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 ...
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...
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, ...
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...
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...
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...
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...
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 ...
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?
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...
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...
In one chapter, the PoV character meets up with her sister. Her sister is supposed to be fairly stuck-up and thinks she's a complete lowlife, so she talks down to her the whole time. I have the Po...
I don't mean "sitting down to write", I mean the literal beginning. The story itself starts with my protagonist running. I need to get him to run, then I'll have the rest of it sorted. But won't st...
In one scene, I have a conversation between three characters: A, B and C. A's son and B are involved in something illegal. C isn't aware, and since A and B aren't entirely sure she can be trusted, ...
I understand that if you’ve got two people speaking, you often don’t need speaker tags because it’s assumed that both people take it in turns unless otherwise specified. This keeps the conversation...
Example from my own writing: "Please take care of yourself," she replied. "Health is the most important thing in life, remember that." "I know, Mom." I had already lost count of the numb...
I'm working on a longish short story (I expect to hit somewhere around 5,000 - 6,000 words by the time I'm through) that starts out in third person omniscient POV, mostly because that allows me to ...
The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions or conceptual explanations of the softwar...
I am working on a novel inspired by the Shahnameh - a Persian epic poem by Abul-Qâsem Ferdowsi. The Shahnameh (the title means "The Book of Kings") is structured as a series of interconnected tales...
I understand that I need not to be anxiety about any meetup - just come there and the conversation will flow to itself. However, after two meetups with two of my readers, I realize that I was quite...
Mark mentioned in his answer that plotholes aren't usually the end of the world, and that I shouldn't sacrifice too much of the story and the characters for the sake of logic. But there's a breaki...
