Questions tagged [technical-writing]
Documentation, tutorials, training, user guides, installation guides, design documents, and all other types of technical documentation in any domain (not just software).
494
questions
0
votes
2
answers
60
views
Is there a point to splitting a blog post into multiple parts?
I write blogposts on Computer Science (not specifically about programming though). Usually my posts are 1500 to 2500 words long. The one I am currently writing will probably end up being 7,000 words ...
- 101
1
vote
2
answers
95
views
Is there a good term for instructions that are presented in the wrong order?
I'm trying to document/comment on an error someone is making in their technical writing, and I don't want to give half a page of explanation. I thought I'd heard a writing term for it.
It's where ...
- 113
0
votes
1
answer
59
views
'input-file' and 'output-file' vs. 'source-file' and 'target-file' as generic names
When documenting command-line things, it is often necessary to use generic names.
Sometimes I use input and output words, and they play nice:
# example 1
pandoc input_file.md -o output_file.htm
But ...
- 105
0
votes
2
answers
62
views
When vs If, when describing settings and parameters
For a current guide, I'm describing settings of an application where you can toggle the setting from Yes to No.
Which of the following is correct, or better, to use?
When set to Yes, this...
If set ...
- 3
1
vote
2
answers
90
views
Is it a good idea to use Git for document management of technical documentation?
I have compiled the technical documentation for a physical product. It includes documents like user manuals, technical descriptions, maintenance instructions, etc. I have decided that all these ...
- 111
3
votes
1
answer
144
views
Is sacrificing "clarity" for sounding smarter on a college continued interest letter a good idea?
I put "clarity" in quotes because I know it is not the right word but I cannot think of what the correct word should be.
I am writing a continued interest letter for my top college. I have ...
- 145
2
votes
2
answers
104
views
Optimal word distance
In scientific writing, we are often in a situation where we need to think about whether we should write down the full sentence that defines a concept, or we can be more concise without raising any ...
- 123
4
votes
2
answers
490
views
Is it OK to repeat the word implied by an acronym?
Say, we have a sentence like that (found on the web):
The ICAP protocol specifies extensions allowing a client to report the IP address of the client and the origin server involved in the HTTP ...
- 41
0
votes
2
answers
83
views
Technical Documentation and Training System Utilizing Markdown and Live Updates
This may not be the correct place to post this question, but I'm at a loss of where else it can go.
I'm attempting to research a potential documentation system for my company to use that would replace ...
- 1
1
vote
1
answer
74
views
Conveying meaning using "such as" [closed]
I am having trouble deciding if the use of "such as" in sentence 1 conveys the meaning correctly, or does the meaning need to be reiterated like in sentence 2. I hope this makes sense.
This ...
- 11
2
votes
2
answers
115
views
How can I make the process of writing easier?
I came up with an AI image generation party game, and I wanted to tell about it to others. It took me an hour to write the description, even though I already knew all the details in my head. It was ...
1
vote
1
answer
22
views
Should the APA In text citation go before or after organization name when the organization is used descriptively?
As examples, which would be considered correct in APA style?
A:
Researchers from the University of Michgian's Department of Computational Analysis (John et al., 2023) determined that...
B:
Researchers ...
- 13
0
votes
2
answers
91
views
Technical documentation of legacy system software
I have been asked to write the technical documentation for a legacy system, which I am working on.
The documentation is trying to target new joinee developers and QAs.
I have few confusion about it:
...
- 101
0
votes
2
answers
87
views
Thoughts on using "looking to" in marketing content
I've been writing content for years, and over the last 6 or so, in marketing for software companies. Very often, I'll see sentences include "looking to" as a way to explain that the reader ...
- 19
-1
votes
1
answer
48
views
Quoting a quote of a person who was interrupted in a scholarly book
ROBERT Thank you. Ladies and gentlemen, let me tell you a story. It
begins with a garden, a cherished place of solace for my family...
ROBERT ...and that's when I discovered the irreparable damage.
...
user36239
0
votes
2
answers
85
views
What is a good way to reference the directionality of an API integration in a succinct way?
I am responsible for product X. Product X has bi-directional connectivity with other systems A and B.
When I am referring to data coming from A in to X, I can say:
"Inbound interface from A to X&...
- 101
1
vote
1
answer
45
views
How to write for an updated edition?
I have a wargaming rulebook that I self-published over a decade ago, that has some interest around it. (Overall, the form is a combination of technical writing + creative design components.) I've been ...
0
votes
1
answer
82
views
Do you include footnotes in technical documentation served on the web?
Footnotes are less commonly used in technical documentation on the web compared to traditional printed documents, or at least this is my own personal experience on the matter. This is because ...
user36239
0
votes
3
answers
178
views
I’m back in graduate school and I’m struggling with writing APA. What’s the best way to learn?
What is the best way of learning APA writing if you have never written in that format?
- 1
1
vote
1
answer
78
views
Where do I get steady technical content writing work?
I am an electronics engineer with UG and PG degrees. Post qualification, I have 9 years of experience in my field. For the past three years I have been freelancing in technical content writing. Up to ...
- 21
3
votes
1
answer
80
views
How do you structure a term paper that involves comparing journal articles?
As part of a course on statistics and stochastic processes, I have to read 3-4 journal articles and write a paper explaining and comparing them and explaining my learnings from them as they relate to ...
- 145
0
votes
1
answer
579
views
How do you cite a Stack Overflow answer?
How do you cite a Stack Overflow answer? Let's say I want to copy and paste a code solution that someone provided for a question asked on Stack Overflow, how do you cite that in a programming textbook ...
user36239
1
vote
2
answers
124
views
How do you transcribe a quote with errors?
How do you quote someone whose native language is not English? Let's assume that the person make several grammatical mistakes, how should you quote them, do you quote them verbatim or do you quote ...
user36239
1
vote
1
answer
176
views
Is a call to action always necessary in a sales pitch?
I heard that in a sales pitch you should always include a call to action at the end. The reason for this is that a call to action can significantly increase the likelihood of converting a prospect ...
user36239
1
vote
0
answers
84
views
What is another way to describe comparing two documents that say the same thing and selecting the best one? [closed]
What is another way to describe comparing two documents that say the same thing and selecting the best one?
0
votes
1
answer
67
views
How do you find who are the lead authors if there's more than one?
https://arxiv.org/abs/2203.04472
How do you find who are the lead authors if there's more than one?
I was looking at the above paper, and I was trying to know who are the lead author so I can cite ...
user36239
0
votes
2
answers
107
views
Can you have footnotes inside footnotes?
Let's take an example. Let's say I have the following foonotes. "Here, the author is making an indirect reference to the expression "(something) fighting" often used in esports."
...
user36239
3
votes
2
answers
363
views
Should you respect Japanese punctuation rules when citing something using Japanese characters?
From the Wikipedia page on Japanese punctuation:
Double quotation marks (二重鉤括弧, nijūkagikakko) are used to mark quotes within quotes: 「...『...』...」 as well as to mark book titles (Japanese does not ...
user36239
6
votes
1
answer
86
views
Does the only figure in a document get labeled as Figure 1?
If a document references only one figure, is it identified as "Figure 1" or no number assigned?
1
vote
2
answers
322
views
What are the guidelines for using articles in technical writing?
When writing technical documentation, I commonly include articles ("the" and "a"), as I think it makes thigs clear and natural to read:
According to the customer's requirements, ...
- 113
0
votes
0
answers
35
views
Comparison of two categories over a specific period of time
Year: 2009 / 2019
Mobile use: 15% / 26%
Table use: 5% / 19%
what is the correct way to describe changes in two different years? I have tried to describe the changes in three different sentences,...
0
votes
0
answers
49
views
How to detect if a research team is outsourcing writing to increase paper publishing?
I have suspicions of a situation where a Computational Science research group is using paid writing services (outsourcing, using AI or human services) to increase their publication ratio in scientific ...
- 101
0
votes
2
answers
103
views
Have you ever heard of the word electromobilists?
I have to check my company's English translations for a new product they have made. The product is an electrical wall box for charging electric cars. They wrote the following sentence:
Ideal for ...
- 103
1
vote
2
answers
347
views
Quoting someone who used a racial slur?
When quoting someone who used a racial slur, should you censor the racial slur, and how should you do so?
I said that he's a *****. That's what I said.
When quoting someone who used a racial slur, ...
user36239
1
vote
1
answer
100
views
In story telling using Month, Date and Year from the past
When you are narrating and you would like to state the month, date and year from the past like September 8, 2019. As an introduction to your sentence, is it right to say "It was September 8, 2019,...
- 11
2
votes
1
answer
113
views
"Notes" as admonitions and "Notes" as a section with endnotes
In technical writing, it is common to use so-called admonitions, also known as notices: see "Notes, cautions, warnings, and other notices" in the style guide for technical writers by Google, ...
- 129
14
votes
8
answers
4k
views
Which is more readable - array of ints or int array?
A similar example is field of carrots or carrot field.
The latter feels better to me, especially in the carrot example, but when asking colleagues they preferred 'array of ints'.
I'm not a ...
- 251
1
vote
1
answer
78
views
When hiring an animator or an artist, how do you insure that you don't become solely reliant on that artist or animator?
When hiring an animator or an artist, how do you insure that you don't become solely reliant on that artist or animator? When writing a script and giving art direction through writing, how do you ...
user36239
-1
votes
1
answer
56
views
How can I avoid accidents when writing special characters with the [alt] key? [closed]
Writing some characters require a combination of keys that include the [alt] key and some digits from the numeric pad. For instance, [alt]+[174] will write a Spanish quote («). Such combinations only ...
- 1
3
votes
2
answers
204
views
Using "etc." at the end of list introduced by "e.g."
According to the Strunk & White's The Elements of Style (p. 46)
at the end of a list introduced by such as, for example, or any similar expression, etc. is incorrect.
However, I have seen "...
- 141
0
votes
0
answers
131
views
Workflow for Markdown or Asciidoc documents
I write a lot of teaching material on using coding languages. I have taken to using Markdown because it’s very easy to just get into it and mark up headings, tables and code samples.
The software I’m ...
- 233
1
vote
1
answer
77
views
When describing a logo to an artist you've hired, what should you write and in what format?
When describing a logo to an artist you've hired, what should you write and in what format? Tried to find some documents intended for artists, so that I can have an artist reproduce my design from ...
user36239
1
vote
2
answers
196
views
How do you accurately describe a race track without using an image?
How do you accurately describe a race track without using an image?
Let's say you have this image, but you can't use it as a reference. How do you manage to exactly describe it in a way someone could ...
user36239
3
votes
1
answer
31
views
What are the conventions for formatting links to two API references in software user guide text?
Background
I'm working as a technical writer on a software project where there are three related documents: a user guide, a Python API reference and a C++ API reference.
The user guide describes how ...
- 33
-2
votes
1
answer
118
views
Semicolon and period in software instructions
I'm writing a software manual and I worry about my semicolon usage. I believe I'm using them correctly, but it's not that I have to.
My project is a software manual.
People scan for the information ...
- 301
2
votes
2
answers
62
views
Referring to an earlier defined phrase so that it's not taken literally
Say I define a phrase like 'pen' or '10 miles'. Then when I refer to these defined phrases inline in the text, how should I refer to them to let the reader know that I am referring to the defined ...
- 21
1
vote
2
answers
177
views
Resources for beginner/intermediate writers
I'm an undergraduate student who's currently self-studying writing in quarantine. At present, I've read some books and browsed writing workshop websites on academic or technical writing. However, the ...
- 29
0
votes
1
answer
99
views
Does a technical writer need API experience for writing API documentation?
I am a technical writer that currently writes for the aviation industry. I got a job offer for an API technical writer position. They said I don’t need API experience, but they think my experience ...
- 136
0
votes
1
answer
110
views
Is scientific writing equal to research paper writing? [closed]
I am just not sure if scientific writing is same as research paper writing.
1
vote
1
answer
297
views
Starting a sentence one word before a new line [closed]
I am curious if starting a new sentence right before a new line, in this case leaving only one word before the new line, is correct. I am having trouble explaining even what this situation is, but I ...
- 11