Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.

learn more… | top users | synonyms

11
votes
2answers
96 views

How to clarify the objects of a sentence's two pronouns?

I am trying to describe a process. There are two players in the scenario. Player A tries to find player B. If player A finds player B, then player A tags player B. Something like that. Here is an ...
2
votes
3answers
45 views

How to move back to main section after done writing a sub-section

I am writing a paper but I don't know how to move back to main section after done writing a sub-section, like this 1.1 Main section 1.1.1 sub section 1 1.1.2 sub section 2 but as I write long sub ...
6
votes
2answers
65 views

Starting a sentence with the name of a program or command-line tool: capitalization?

Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you ...
2
votes
1answer
112 views

How to structure the text when describing the steps of a procedure which has simultaneous processes?

I have to further explain my intent here. I'm writing down some procedures in operating manuals and servicing manuals. I mostly use numbered lists and sometimes just bulleted lists. Recently I started ...
0
votes
1answer
54 views

How to communicate multiple meaning in a sentence more concisely?

Good day everyone, I have the following sentence: Around 70% of small businesses in the United States struggle to hire qualified employees, and around 50% attribute this challenge to ...
3
votes
1answer
69 views

How do I announce an area-restricted feature without discouraging the rest of my visitors?

I want to make an announcement to my users at my website about a new feature launch. However, in its first phase, this new feature has limited access - it will be supporting only one city for now, and ...
3
votes
1answer
81 views

How to communicate two elements of different general syntactic/semantic type in the same sentence?

I have the following sentence, NAME is a community that helps each other code better by rating each other's efforts and helps managers pair with other fellow developers I was suggested by the ...
19
votes
12answers
3k views

Can basic grammar rules be skipped when writing text for machine safety labels?

First of all I'm completely against this idea but a few people who contribute to the technical documentation project constantly suggest that to attain a short, quick, economic, comprehensive message ...
4
votes
1answer
60 views

Should I use contractions in a technical tutorial?

In a technical tutorial which fits better: In this tutorial you'll learn or In this tutorial you will learn or in general does it make no difference?
0
votes
1answer
53 views

How can I rewrite the sentence for technical writing style [closed]

I want to rewrite my sentence in technical writing style. Could you help me rewrite my sentence? Thank you in advance The proposed methods has 4 variables need to update in a optimization process, ...
0
votes
1answer
24 views

Referring to a diagram

In a math book, should I write "diagram 3" or explicitly "diagram at the figure 3", when referring to a diagram in a displayed figure? (The title of the figure (as autogenerated by LaTeX) is "Figure 3....
3
votes
3answers
138 views

Web-based WYSIWYG Markdown editor with commenting?

My question is similar to this one, but with (hopefully) a clearly defined use case: sharing and reviewing basic tech docs with a minimal, intuitive GUI. I'm producing technical documents using MS ...
0
votes
2answers
78 views

I am writing a book on web design. What elements should I remove to avoid copyright issues?

I am writing a book on web design, titled Best website design. I will list photos of some good-looking portfolio websites in the book. Do I need to take permission from the website owner? Will it be ...
5
votes
3answers
60 views

Is there a standard for describing a form in a programming specification?

I'm a web programmer at a small web firm. When we have a larger programming project, I write a specification document for the client to review, make necessary changes, and eventually approve. Our ...
0
votes
1answer
50 views

Requirements engineering: getting the most out of Word?

Are there any features in MS Word (ideally for Mac) that can be helpful in requirements gathering/tracing? As an example, at present I'm using comments in the Review pane to index requirements and ...
8
votes
9answers
322 views

Can technical writing suck less

I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider myself a reasonably proficient ...
-1
votes
3answers
119 views

High Tech Audience

I have to write a simple introduction on the topic HTTP and its audience will be high tech. I am having a bit of problem in how to describe it in high tech audience? Can any one would suggest me how ...
1
vote
3answers
52 views

How do you write a good product description? [closed]

Are there any rules or procedure to write a great product description. Any examples of good desciptions online?
1
vote
1answer
48 views

should I put the reference number after the dot or after a space? [duplicate]

I am writing my thesis. and I need to know the correct way of putting the reference. for example: this is a sentence taken from someone [2]. this is a sentence taken from someone[2]. ...
2
votes
1answer
33 views

Should I use figure titles for diagrams on the web?

Should I use figure titles for diagrams in web content if the diagram already has a caption? Guidance or references are appreciated. The context is a marketing page whose basic structure is shown in ...
2
votes
1answer
87 views

Ways to influence the readers subconscious?

Are there any proven techniques of influencing the readers on a subconscious level? Preferably techniques involving only words as I'm interested in writing technical books and I don't have the liberty ...
4
votes
1answer
71 views

Plural of single letter variables

Excuse me if I am on the wrong StackExchange site. I write about Physics in English and typeset that with LaTeX. So I have a variable c, and there are two of them in the same expression. I want to ...
4
votes
2answers
91 views

Attracting and retaining volunteers to edit technical doc for open source projects

I volunteer as an editor for the Mozilla Developer Network (MDN), an organization that creates free open source software such as the Firefox browser. MDN has a large number of technical topics ...
1
vote
1answer
52 views

Concepts for more interesting Introductions in Papers

What are the key concepts for writing introduction text more interesting to the reader? An example: The Deutsche Bahn AG is the company with the most energy consumption in Germany. It has ...
1
vote
1answer
83 views

How can I avoid using the first person in a report when directly referring to work and experiences I have had?

I have been asked to write a report on the company I am working at during a placement from University (I am on an engineering programme). There was not much guidance given on what the content of the ...
1
vote
1answer
10 views

APA Headings- Frequency

How often should you use a heading? Are there any guidelines or limitations to using headings too often (i.e., every paragraph, every other paragraph, etc.)?
2
votes
3answers
473 views

Use of the Oxford comma

The oxford comma is the second comma in the sentence I like the colors red, white, and blue. Every grammar textbook I've ever seen, as well as the major style guides, feels that this is "proper" ...
1
vote
2answers
103 views

How I should handle gender-neutral pronoun in technical writing? [duplicate]

I am writing API documentation for a mobile loyalty program and I am not sure which of the following is better wording: 1) When the user requests for their visit and order to be registered in their ...
2
votes
1answer
78 views

How to reference an ISO/IEC?

I'm doing some college work and I'm using ISO/IEC 27000 Information technology — Security techniques — Information security management systems — Overview and vocabulary. In Word, I have set up the ...
1
vote
1answer
30 views

Is it necessary to explain what is written in upcoming chapters?

When writing a technical report, is it necessary to explain what is written in upcoming chapters? For example in my introduction chapter, I may have a sub-chapter called "Forthcoming chapters" which ...
2
votes
2answers
54 views

Wording of comparing X vs Y and X vs Z but not X vs Y vs Z

As per the title I compared my system against two other systems separately but I'm worried about it coming across as that it was a three way comparison. Neither of the below titles convey what I want ...
5
votes
1answer
95 views

Format keyboard keys in documents

I'm writing a guide to give step-by-step instructions to complete some tasks on the computer. At some points, I need to indicate pressing keys on the keyboard; how may I format the letter/symbol to ...
5
votes
2answers
72 views

How long is too long for a blog post?

I'm at the very beginning of a blog post for Worldbuilding Stack Exchange's blog, Universe Factory, written in conjunction with an answer to a question on Worldbuilding. It's going to about astronomy (...
2
votes
2answers
106 views

Authoring tool for interactive documentations

I am searching for an application (Desktop- or Web-App) to write and create interactive documentation (especially technical documentation). I like Madcap Flare for technical writing, but I'm looking ...
1
vote
2answers
80 views

Report writing: should I use ® © symbols?

I am busy writing a report for university. For this, I did some programming in MATLAB and simulations in Aspen Plus and HYSYS. When referring to these software in the report, should I symbols such ...
4
votes
3answers
82 views

How to work on a new software feature that affects different topics

We're working on a software manual with several chapters and topics and, so far, these are mostly self-contained. This means we have a dedicated chapter for "connectivity" and do not mention ...
1
vote
1answer
86 views

Relative clause or a new sentence. Which is better in an introductory paragraph?

I wrote In our approach, we rely mainly on the page's content to detect a data region, which in our definition is comprised of a node or a range of nodes in the DOM tree, constituting a ...
5
votes
5answers
351 views

How do I get rid of the tic of paired adjectives, predicates, etc.?

In technical writing, I have a tic of writing in pairs. Some examples from a recent piece: "When you speak, be sure to be clear and concise." "Face to face conversation is personal and private." "...
-1
votes
1answer
52 views

Are there any proper ways of using/implementing “e.g.” in a “Research Narrative”?

Are there any proper ways of using/implementing e.g. in a "Research Narrative"? I am working on a "Research Narrative" (I must write in both ALA and MLA format). I am curious about this e.g. but I ...
3
votes
1answer
229 views

Technical writing — best solutions for gathering and compiling data/information

Seek best solutions for information collection, compilation, aggregation Background I'm a newer technical writer working for an industrial fabrication company. We make an awesome B2B product that ...
0
votes
3answers
43 views

academic writing: direct quote

I have a simple question regarding scientific quotes. Which of the following alternatives is correct? Alt. 1: The literature has made substantial strides towards identifying causal effects of X on Y ...
0
votes
2answers
66 views

Can you use et al. in a Bibliography?

In the text, I have, e.g. "...a major role to play in role-playing (Smith et al., 1990)." But can I use the same abbreviation in the bibliography? Smith, K. et al. 1990. Playing major roles ...
2
votes
3answers
123 views

How to find the balance between research and the obvious

I'm embarking on writing my first popular science book on a controversial subject. For sure the writing must be rational, coherent with a clear train of thought and littered with references to be ...
1
vote
5answers
123 views

technical subjects - non-fiction vs fiction

This is a question I tried to ask in Novelizing non-fiction, is it worth it? But was un-clear and maybe too generic. Let’s say I am a scuba diving expert and I could write a non-fiction book about ...
2
votes
5answers
107 views

What is considered an acceptable length for a technical document?

I have written dozens of technical and requirement specifications, and edited dozens more in 8+ years of engineering. The largest I have drafted was perhaps 100 pages, but maybe 30-50% of it was ...
6
votes
4answers
132 views

The fine line between accurate science, and confusing my reader

I recently wrote a blog post (original here) about a scientific study. At the end, I included some "fine print" which states, among other things: Correlation does not mean causation. It’s ...
0
votes
1answer
34 views

Footnote placement — inside or outside terminal quote?

When you are referencing inforamtion in the footnote, is it customary to put the footnote number inside the quote or outside? For instance is it: "The pink pig."1 or: "The pink pig.1"
3
votes
1answer
104 views

Citing an article with multiple authors in APA style

I have been trying to go through Mayfield Book on Technical Writing to find out how to do an in-text and parenthetical citation of a source that I found online. The source is an article from a popular ...
0
votes
1answer
49 views

How to cite a report in APA style

I have been trying to go through Mayfield Book on Technical Writing to find out how to do an in-text and parenthetical citation of a source that I found online. The source looks like a report with ...
0
votes
1answer
258 views

What is it called when an author uses vague words for concrete concepts, “hedging”?

As an editor for an academic press, my pet peeve is when authors write sentences like "attempt to conceive of a possible approach to resolve X" instead of "try to resolve X". Obviously one big ...