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

learn more… | top users | synonyms

11
votes
9answers
2k 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 ...
2
votes
1answer
24 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 ...
2
votes
1answer
261 views

Using the Minto Pyramid

Using the Minto Pyramid, should I order the paragraphs of my paper by going through the rows of the pyramid like this? Thesis > Why > How > Where > A > B > C > D > E Or should I start at the top ...
1
vote
3answers
469 views

Technical Documentation Voice Preference : “Active Voice” - “Passive Voice” - A Mixture of both

We are working on a technical documentation project which includes the rewriting, modernization, restructuring, enrichment of the content. I'm doing the content rewriting and translation parts of the ...
0
votes
0answers
16 views

When does sponsored content work with adverbs? [closed]

I work a job on a website, writing articles. Lately, we've been transitioning from personal accounts and topical subjects to interviews and Top 5s with our company-hosted events sandwiched in between. ...
3
votes
1answer
49 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?
1
vote
1answer
87 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 ...
5
votes
5answers
4k views

What are the advantages of different date formats in resumes and CVs?

I've seen a somewhat related question, but it doesn't answer my question quite right. Say you're writing an event that happened on a single day, and you need to put it in your resume or CV. So how ...
66
votes
15answers
5k views

What's the modern way to handle gender in tech writing?

Back in my day, I was taught to use masculine pronouns. The user chooses a password, and then he types it in the text box. I'm fine with that. but a male coworker insists on using he/she, ...
3
votes
3answers
124 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
1answer
47 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
23 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 ...
6
votes
4answers
614 views

Breaking Into Technical Writing - Where to Start (from a programming background)

I'm currently in the process of expanding my company from doing coding & web development to more technical writing and freelance tech journalism. Although my background is mainly in technology, ...
0
votes
2answers
60 views

Writing a book on web design, what elements should I remove to avoid copyright issues

I am writing s 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 ...
8
votes
9answers
274 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
vote
3answers
50 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?
2
votes
5answers
105 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 ...
5
votes
3answers
58 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 ...
3
votes
2answers
43k views

Multiple authors in MLA header

I'm writing a group paper and I was wondering whether there's a correct way to list multiple authors at the top of the first page in MLA format. Normally the header would look something like: My Name ...
16
votes
7answers
3k views

Should one use the legal “shall” in requirements documents and specification documents?

At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of ...
0
votes
0answers
30 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 ...
7
votes
4answers
368 views

How can you write less to say more?

Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader. In technical writing the later is very typical (at least for me), one can tend ...
0
votes
1answer
33 views

Write a presentation of a dissertation [closed]

We have made a dissertation about a type of insect called Pine Processionary Moth. We have applied some statistical methods on it: data analysis and cluster analysis!! We have almost finished, but I ...
6
votes
8answers
2k views

Is it overkill to follow style-guides for technical writing?

I currently work for an engineering company as an electrical engineer. A good chunk of my time is spent writing testing reports or instruction documents. Currently my company doesn't have any sort of ...
2
votes
1answer
88 views

Graphical presentation method nomenclature

I'm part of a technical documentation team where I'm suggesting the document designers different methods for graphical presentation. Each time I need to talk about a method I have to look around and ...
-1
votes
3answers
106 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 ...
8
votes
6answers
3k views

Demo data in screenshots! What are the best practice?

My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making ...
6
votes
3answers
421 views

Using LaTeX with publishers?

Background: Im working on a rather long instructional book, and have just started trying to use LaTeX. The book doesn't have any scientific notation in it, and most of the diagrams I made in other ...
4
votes
4answers
1k views

What is the best way to learn technical writing?

I have a moderate level of skills in technical writing (TW) having gone through graduation in engineering. I was wondering what would be the best way to sharpen my knowledge. I am also interested in ...
1
vote
1answer
37 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
32 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
1k views

What is Content Testing?

What is Content Testing? Are there content testing tools available, or is content simply tested manually for quality?
2
votes
2answers
102 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
1answer
74 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 ...
2
votes
1answer
83 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
2answers
87 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 ...
3
votes
1answer
63 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 ...
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 ...
3
votes
2answers
215 views

Any advice on how to learn DITA for technical writing?

My situation is such that I will be looking for a new job next week as this contract ends. For a tech writer, it is good to have DITA on the ole' resume. So, I just wanted to know if anyone has a site ...
9
votes
13answers
2k views
1
vote
1answer
9 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
453 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
78 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 ...
15
votes
5answers
7k views

Writing a programming book: how to present directory structures

What is good/preferred way of presenting directory trees in programming books? My main criteria are following: It should be readable and intuitive It shouldn't take too much page space It ...
2
votes
1answer
66 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
2answers
97 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 ...
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
51 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
87 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
70 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 ...