All Questions
517
questions
-1
votes
0
answers
40
views
Sections a few paragraphs long without headings
Context I'm looking through the English translations of Truppenführung [1], an old German field manual from the 1930s. An old translation done by the US military is freely available on the internet in ...
- 1
0
votes
2
answers
51
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
83
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
44
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
64
views
Short description of a software component/product?
I write documentation for a software vendor. What is the best way to describe a software component in short if we must mention both its title and function? What wording would be preferred?
the ...
- 41
0
votes
2
answers
55
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 ...
- 1
1
vote
2
answers
87
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
143
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
484
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
74
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
114
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
86
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