4
votes
3answers
137 views

How can I express this fragment more clearly and concisely?

For the 'who is this application for' section of an application user guide, I have the following alternatives, I'm not happy with either one. How can I convey both elements more clearly and ...
6
votes
4answers
406 views

Which goes first: summary, background or justification?

I am trying to write a long expository piece and cannot figure out which information should come first. Here are three candidates: A summary/abstract lists the main points, without necessarily ...
5
votes
6answers
456 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
10answers
277 views

An alternative to saying 'users' when describing features

I'm creating some copy describing new web-app features for a number of different audiences (users, managers of sections of the site, owners of sub-sites which use our platform etc.). I'm finding ...
5
votes
3answers
858 views

When is it acceptable to use the first person (“I”, “we”) in technical reports?

When is it acceptable to use the first person ("I", "we") in technical reports?
8
votes
13answers
1k views

Does a technical writer need a technical background?

Does a technical writer need a technical background?
7
votes
3answers
474 views

What are the key skills for a new technical writer?

For those that are just starting out, what are key skills they should have or learn to be a good technical writer?
8
votes
8answers
1k views

Good Outlining Solutions For OSX?

I write technical non-fiction and find that I cannot write well without first constructing a detailed (10-20 page) outline. Are there any good outlining solutions for OSX? Apps? Templates in Microsoft ...
23
votes
6answers
1k views

Writing first programming book

I was recently asked if I was interested in writing a book for a pretty reputable publisher, which of course I accepted. I am not a writer by trade, I am a software developer with some technical ...
4
votes
5answers
261 views

Using uncommon abbreviations

Something which I see all the time in (popular) science writing is the use of abbreviations to indicate concepts. For (a made up) example: So when we're dealing with Anachronistic Meta Mechanics ...
2
votes
7answers
831 views

Verb tense for technical document titles

I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names. My ideas are: Continuous (-ing) form: (e.g. "Creating a Cluster", "Creating ...
22
votes
10answers
510 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 ...