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

learn more… | top users | synonyms

0
votes
2answers
129 views

Am I correctly referencing chapters which belong to the same book?

Looking for some help on how to reference chapters in a book inside of a booking I'm helping with. Should I be capitalizing Chapters 3 and 4 and would referring to chapters simply by capitalized ...
3
votes
2answers
3k views

Are contractions antithetical to academic writing?

This question is very specific to academic writing: I used the contraction "don't" instead of "do not" in some of the papers. Some of the reviewers mentioned that "don't" is not a formal style of ...
5
votes
6answers
475 views

Does this feel like natural English?

Although I'm pretty confident in my English, I'm not a native English speaker. I need to write a short introduction for a symposium; I'd like to know if you think this paragraph feels like 'natural' ...
9
votes
13answers
2k views
2
votes
1answer
130 views

What resources will teach me about the state of the art in technical writing?

I've been asked to modernize some technical documentation - user manuals in particular. I have some guidelines, but a lot of free rein to take it in whatever direction I think is worthwhile. Where ...
4
votes
1answer
203 views

Habits and routines for my first tech writing job

A Japanese company has offered me a gig helping translate an Android1 business application + documentation into English. Their staff will do a rough translation, and I will polish it into something ...
5
votes
4answers
342 views

How can a new writer make a realistic estimate of his work rate?

This question relates to my earlier question Habits and routines for my first tech writing job which I was told to split into two parts. My first technical writing / translation gig starts soon. A ...
3
votes
1answer
271 views

Path to publishing a technical book

I'm 21 years old female from South India. I would like to publish a book which concentrates on any one latest computer technology. Now, I have completed my BE- Computer Science and Engineering. I'm ...
3
votes
3answers
232 views

What's the correct vocabulary for a web application tutorial?

I am writing a tutorial on how to use a specific web application and I don't know which verbs to use. Shall I use "click" for buttons? But what if the user doesn't use a mouse? Contrary to "normal" ...
11
votes
4answers
4k 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
231 views

Using Glossary Instead of Footnotes (for translation/transliteration)

I am writing a technical report with keywords which are mainly English. I am using a Glossary at the end, which describes translated keywords. Is it a replacement for footnotes or I should just keep ...
0
votes
1answer
108 views

website to publish article on high-performance cluster computing?

I am writing a tutorial-type article on high-performance cluster computing. It is aimed at researchers and grad students who want to use clusters to answer scientific questions, especially in the life ...
56
votes
13answers
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, ...
1
vote
4answers
138 views

How can I express this more clearly or concisely?

I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems ...
22
votes
10answers
551 views

How can one make technical issues more accessible to a non-technical audience?

Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc. Lately, I find that some of the topics I am trying to present are much more technical ...
5
votes
2answers
305 views

Why are license agreements, disclaiming letters and others written with capital letters?

We know that reading sentences with capital letters is hard. I noticed that some documents are still written with capital letters. Why are license agreements, disclaiming letters and others written ...
3
votes
1answer
113 views

Which is a better composition?

Consider following sentence composed in different ways, And the worst, when memory is full, creation of new node will return a NULL. And the worst is when memory is full and a new node is created ...
2
votes
4answers
93 views

Advice on interface text in a videogame

[This fits somewhere between technical writing and user experience, so perhaps this is the wrong board] I'm developing a modification to a popular videogame (a Playstation One RPG), with the ...
2
votes
3answers
143 views

Would it be weird if I write “a simple sample something”?

Not getting too technical, I am writing a configuration file for a piece of software I have developed. This software allows others to write "services" and attach them to my software. I have written a ...
3
votes
4answers
70 views

In a “learn to do X” book, should a section review come before the quiz / exercises or after?

I am writing a book on how to program in C#.NET. Each of the sections follows this format: Section Aims Content Section Review Quiz Exercises The section review is there to summarise all of the ...
3
votes
5answers
1k views

How can this technical message be made clearer?

How could this technical sentenced be improved for better clarity? Cannot translate the ‘name1’ concept1 to the ‘name2’ concept2 because the higher precedence ‘name3’ concept3 also exists, which ...
2
votes
2answers
128 views

What are “industry leading royalties”?

In the breakdown description I received from a publisher, they mention that they also pay industry leading royalties of ##%. What does that mean?
5
votes
5answers
193 views

How to write about things which depend on each other

I am writing a technical documentation about a product. Now problem is there are many interrelated and interdependent concepts. I am just confused how to put them in order. I mean if I talk about ...
0
votes
1answer
84 views

Giving something an alias

Within a technical document I want to refer to a system or process by a shorter name. I have no idea what this process is called so searching the internet is not getting me anywhere. Is this correct? ...
1
vote
4answers
123 views

Is this description of my small productivity application clear enough?

I wrote a small productivity application, Tomate. Since I'm not a native English speaker, I'm afraid the description of the project may not be clear enough for potential users. Can you help me improve ...
4
votes
4answers
154 views

Where to find authors for highly technical articles?

I've looked at some of the largest outsourcing sites. These have huge amounts of software developers, and huge amounts of casual writers. I'm having enormous difficulty finding authors that would be ...
5
votes
3answers
259 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 ...
2
votes
2answers
182 views

Is this blog post clear and coherent?

I wrote a pseudo-technical blog post trying to apply some game theory concepts to s/w startup industry. This is my first serious attempt at tech blog writing. Iwas left feeling disappointed by the ...
4
votes
3answers
145 views

Feedback on technical blog post

I've recently composed a blog post about World of Warcraft Authenticators and would love for some feedback as per the quality of writing. Obviously no matter how many times I read it there's no ...
1
vote
3answers
150 views

How do I use my blog as a platform for practice and improvement?

I've recently followed the advice of our very own Jeff Atwood and started a blog site in order to become a better writer and communicator. My goal is to improve my skill at technical writing and ...
0
votes
1answer
558 views

What are the names of the different levels of English?

In a recent discussion regarding software manuals, we came across the issue of different styles of writing / speaking in English. I am having a hard time finding a list of the different styles, such ...
4
votes
1answer
727 views

Is there a style / terminology guide for Android OS application documentation?

This relates to my earlier question: My first professional writing job: any advice? I will be involved with writing documentation for an Android OS business application. Is there an Android style ...
-1
votes
2answers
127 views

What help is there for a technical reseacher/writer that can't edit?

I've got a personal professional goal - I want to write a thesis, build a system, change the world. That's my way of saying that my thesis needs to be something I can develop into a functional system, ...
1
vote
3answers
293 views

How can I manage screen shots and other graphics for maintenance?

Our ~1500-page documentation set contains numerous screen shots and related graphics (schematics, flow diagrams, etc). Sometimes the user interface changes and we have to update all the affected ...
4
votes
1answer
219 views

What tense to use in an academic paper when speaking about correspondence?

What is the correct tense to use in an academic paper when speaking about correspondence? Say one of my source materials is a letter written by someone named William, in which he says he went to the ...
6
votes
2answers
871 views

Should I prefer long or short sentences in scientific writing?

Currently, I am writing papers with rather short sentences: About half of them contain around 20 words, about 10% to 20% even less. I am doing this for three reasons: I find short sentences easier ...
6
votes
2answers
446 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, ...
7
votes
1answer
3k views

Citing Myself As a Source

I'm writing an academic paper on ethics in robotics. I have a previous paper that I wrote and would like to use material from it. If I use the material from this paper, that I wrote, do I need to ...
1
vote
3answers
1k views

Where should index and glossary appear in a report?

I am writing my thesis and now wonder whether I should typeset index and glossary as an appendix or after them. There's no department-level accepted writing style, so my adviser's opinion might be ...
10
votes
3answers
301 views

Is it legal to write about trademarked material and use the terms?

I am contemplating writing a technical book (and probably self-publishing it) on a proprietary programming interface for a well-known software package produced by a very large company. The company ...
1
vote
1answer
59 views

Numeral Citation Scripts

I am writing a report in Farsi and using ieeetr bibliography style for my references. This style uses numeral references like [1] [2] etc but regarding context (Farsi) I am using Arabic number scripts ...
1
vote
0answers
59 views

Regarding Professional Report [closed]

I am new in the working world and I happen to be given a lot of tasks related with creating report. Later on I heard people give me comments that my sentence structure and my word choices are not ...
2
votes
1answer
2k views

APA (sixth edition) citation for the Fourth Assessment Report

I'm trying to cite a source from the IPCC Fourth Assessment Report: http://www.ipcc.ch/publications_and_data/publications_and_data_reports.shtml I'm fairly new to APA in general and I'm struggling to ...
5
votes
5answers
154 views

Interesting and easier-to-read alternatives to the scientific academic article

Short version: What is an equally informative, but more interesting alternative to typical academic-article-style scientific writing? Longer version: I love writing, I do a lot of it – fiction and ...
2
votes
0answers
66 views

How to use His/My/Your permutations in adressing persons [closed]

I'd like to understand the rationale of when, why and how His/My/Your are used in titles of addressing people. For example, the standard commonly accepted uses are: "His Honour"("His Grace", or ...
0
votes
3answers
148 views

Risk Assessment in Technical Standards Documentation

In your experience, are sections on risk and risk management typically part of technical standards documentation? For example, in a document that describes how the Network Time Protocol is ...
0
votes
1answer
208 views

How would I say this in the reverse?

I am sending out a message to all users that have filed a bug report for my last game; the one I shut the server down on. The broadcast message I am sending is going to be an email, but I'm not ...
6
votes
6answers
300 views

Book recommendations for writing better technical papers

My employer has presented me with two books to read to help me write better technical papers and emails. Essentials of English Grammar and Handbook of English Grammar and Usage. I have read through ...
5
votes
2answers
406 views

How do you introduce terms?

There's a few different styles for technical (academic) papers. Which is the preferred style to introducing new technical terms? For example, here is a paragraph I have that I don't like, because I ...
3
votes
1answer
4k views

What counts as a word when dealing with a word limit?

I am trying to determine if it will be feasible to revise a manuscript for a journal that has a 6500 word limit. Currently, the manuscript is between 7500 and 8000 words long, depending on how I count ...