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).
474
questions
0
votes
1
answer
36
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 ...
- 7,234
1
vote
2
answers
77
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 ...
- 7,234
0
votes
0
answers
46
views
The reviewer pointed out some grammatical errors in my paper. Is it right for me to change it?
The reviewer:
Bottom of page 2 “Inspired by their works…” is a run on sentence that has some grammatical errors as well.
The source text:
Inspired by their works, we discuss the connection between ...
- 1
1
vote
1
answer
162
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 ...
- 7,234
1
vote
0
answers
18
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
24
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 ...
- 7,234
0
votes
2
answers
58
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."
...
- 7,234
2
votes
1
answer
75
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 ...
- 7,234
0
votes
1
answer
44
views
When you write a book that seeks to inform people about some issue or some event, how do you structure your book?
Let's say I am writing a book about environment policy in China and how China managed to clean the air in its biggest cities drastically by going green, how would you structure a book like that? I ...
- 7,234
6
votes
1
answer
67
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
45
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
32
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
37
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
87
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
0
votes
2
answers
112
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, ...
- 7,234
1
vote
1
answer
59
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
50
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
72
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 ...
- 7,234
-1
votes
1
answer
54
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
154
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
96
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 ...
- 213
1
vote
1
answer
73
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 ...
- 7,234
1
vote
2
answers
143
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 ...
- 7,234
3
votes
1
answer
29
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
109
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
60
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
131
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
79
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
78
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
108
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
2
votes
1
answer
133
views
Effort equivalence between video course and written course
If 1 page of a technical course is worth 1 point, how many points is 1 hour of a technical video course worth, creation effort-wise?
Background and context:
I work in academia in a technical field (...
- 37
0
votes
2
answers
53
views
Citation throughout my book rather than at the end as a bibliography
My book is a health/ wellness/ diet book/ metabolic issues etc. Throughout my book which I am 3/4 of the way through I have added in the website links after a piece of evidence. I have used 95% of my ...
- 1
1
vote
1
answer
191
views
Correct way to write units of measurement in technical document?
"We have 31in of whatever and 4m of whatever etc..."
Should there be a space between the number and the units? Should the units be in italics or normal font? When do the units go in italics?
...
- 135
1
vote
1
answer
40
views
How do you get a patent description proofread?
How do you get a patent description proofread? Is it a service offered by patent office for free as long as you paid the application fees, or is it something you need to get proofread by someone? Also,...
- 7,234
0
votes
2
answers
80
views
How to mark up dialog or menu item names in technical writing
I'm wondering about the correct way to mark up icon/menu item/dialog names in the context of technical writing (user's guide). Here's a small excerpt from a document I'm writing:
Clicking the “...
- 103
4
votes
1
answer
1k
views
What is the process of creating a word using Latin and Greek word parts?
I am trying to create a word that means "division of a single God", but I am having some trouble. If I understand correctly, any word must have a suffix, root and prefix, but sometimes I ...
- 7,234
2
votes
2
answers
81
views
Can we use 'then' after a 'when'?
I know about the logical expression of 'if --- then', such as 'If the temperature reaches or exceeds a particular temperature, then the kettle will turn off.'
But what about situations that involve '...
- 23
0
votes
1
answer
49
views
Should you cite the document you're refuting or only the documents you use to prove your argument in a research paper?
Should you cite the document you're refuting or only the documents you use to prove your argument in a research paper? I am wondering what's the consensus on this, because in my opinion, it doesn't ...
- 7,234
2
votes
2
answers
107
views
How a psychiatrist must talk?
I wrote a scene of a psychiatrist talking to a traumatized child, and I read and read it several times but still not convinced and satisfied with it. Are there any book recommendations or extracts ...
- 956
0
votes
1
answer
85
views
How do you create new words if latin suffixes and prefixes are not sufficient in allowing you to create a new word you want to create?
How do you create new words if latin suffixes and prefixes are not sufficient in allowing you to create a new word you want to create? What are the things people use to make up for a lack of latin ...
- 7,234
2
votes
2
answers
83
views
Best way to explain references to historic currency
What is the best way to explain the pre-decimal British Pound in a text that has multiple references to it.
I already have something written to explain how to convert from pre-decimal to post-decimal ...
- 46
0
votes
1
answer
680
views
Capitalize "million" when using as a unit
When you write "1 Million", should it be "1 Million" or "1 million"?
I would assume capital based on the symbol for mega being 'M'.
- 103
0
votes
1
answer
37
views
Should there be a space between quantitative units?
I understand that the SI standard for units is to have a space between the number and unit:
Unit of measurement and formatting
https://physics.nist.gov/cuu/Units/checklist.html
But, does this apply ...
- 103
0
votes
2
answers
97
views
Database documentation verb choice: If "fieldname" has/contains/is/displays
I'm trying to find the right verb for database documentation. I have to write a lot of these and it is very long; so I am working for a consistent and reusable way to phrase this.
What I have now:
...
- 301
0
votes
1
answer
78
views
Writing about a large Application Programming Interface
I would like to write a tutorial for a large Application Programming Interface, let me call that way. It is a library of many elements, in the thousand range. Obviously, only part of it is frequently ...
- 161
0
votes
3
answers
79
views
Mapping relationships between topics in a non-fiction series
I am working on a series of episodes that will be made into individual videos to explain different technologies and how they interrelate at different levels within a specific application domain (the ...
- 101
5
votes
3
answers
164
views
What is the proper format for filetype extensions in technical writing?
We are writing a collaborative paper that will include various examples of data types. When stating the data type file extension, how should it be presented?
For example,
"The platform will be ...
- 53
0
votes
2
answers
154
views
How do I write a strong hook for an argumentative essay?
The scenario is to write a hook for an argumentative essay. The topic is "Can tigers be kept in zoos?", as they have less space in zoos compared to nature, and for other reasons they should ...
user49075
3
votes
2
answers
181
views
Should I use more transition words? [closed]
I just wrote a blog post, and then I went to publish it on our team blog. The Wordpress instance for the team has this "Yoast SEO" plugin. Among other things, it judges my writing style:
I'...
- 133