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

learn more… | top users | synonyms

5
votes
5answers
398 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 (...
5
votes
6answers
484 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' ...
5
votes
3answers
281 views

Online technical writing classes

anyone aware of or can recommend online training courses for technical writers to improve your technical writing skills? I'm looking for courses that provide video or audio lectures, and teachers ...
5
votes
3answers
1k 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?
5
votes
5answers
350 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." "...
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 ...
5
votes
4answers
431 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 ...
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 (...
5
votes
1answer
91 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
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 ...
5
votes
3answers
144 views

Software for keeping track of book edits?

So I'm writing a new edition of an old textbook, and I need some way of keeping track of what needs to be done, and what I have done. I could use paper - but I tend to lose that. Or even a plain text ...
5
votes
3answers
149 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 consisely?...
5
votes
4answers
161 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
2answers
645 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 ...
5
votes
1answer
254 views

Outlining for white papers

I used to write technical white papers on different technologies. There should be some rules for writing professionals, some home work that needs to be done. I have never gone through any professional ...
5
votes
2answers
243 views

How can you build an interactive tone into articles?

I was wondering about tone in articles lately. My articles don't tend to be interactive. It feels like most of them are just flowing one way. How does actually tone contribute to the quality of an ...
4
votes
3answers
633 views

Do Decimals Bounded Between 0 and 1 (inclusive) Need a Leading Zero?

For a variable bounded between 0 and 1 inclusive, [0,1], should I use a leading zero when quoting a number? E.g. the probability of rain is 0.5 or .5 (I realize this should technically be 50%, but I ...
4
votes
4answers
136 views

Is this title suitable for a chapter section?

Suppose I am writing a chapter about some deep technical subject (say, for instance, "boolean variables"). This theme is riddled with idiosyncrasies and misunderstandings, so I would like to present ...
4
votes
1answer
1k views

Bullets vs. Numbering: which to use when?

A writer can either choose to use bullets or else stick to conventional (or in certain cases non-conventional) numbering. Are there set guidelines about when to use what? Is the use of numbering ...
4
votes
3answers
141 views

Marking a chart that is not based on real data

I want to include a chart in my thesis to visualize an idea but the chart is not based on real data, it just helps me to explain a concept. How can I label it so it's not confused for actual data. It ...
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 ...
4
votes
3answers
150 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 ...
4
votes
3answers
884 views

Is there anything like 99designs for text writing?

I'm not a writer, but a technical oriented entrepreneur.. One of the barriers I always run into is that I'm also the lead guy for providing the content for marketing gigs, speaker bio's and website ...
4
votes
1answer
409 views

in English, is it necessary to capitalize after a colon?

I've seen that each language has its own rules when using the colon. In Spanish, it's not needed to capitalize: Los elementos incluyen: secado, lavado, etc. In French is the same, and even they put ...
4
votes
4answers
3k views

What would sections of a book that are larger than a chapter be called?

I'm writing a technical book, and I want to split my book up into about 3 to 6 very broad sections, each of which would have several chapters in it. Is there a standard name for these broad pieces ...
4
votes
2answers
113 views

What is a reasonable amount of time to spend writing a product overview?

I have plenty of writing experience as an academic and as a technician but am new to technical writing per se. A retailer of engineering equipment wants me to write unique, user-friendly content for ...
4
votes
1answer
57 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?
4
votes
1answer
69 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
4answers
283 views

How can I consistently distinguish among tables, fields, and records in a database?

I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows). I spend a lot of time discussing tables and ...
4
votes
1answer
222 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 ...
4
votes
1answer
138 views

How do I approach rewriting an entire user guide in an agile environment?

I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The ...
4
votes
1answer
84 views

In a FAQ, should a question header take the form “Why does blah blah?” or “Blah blah happens, Why?” And why?

Whilst writing technical documentation, there is commonly a section on troubleshooting or frequently asked questions. I know a FAQ should be real questions - not ones the publisher thinks might be ...
4
votes
3answers
207 views

Should I have an introducing paragraph in every chapter of my description?

I'm about to write a technical description for an industrial process. The description will follow logical blocks, or blocks from the PFD of the process. This a sales document aimed at (mostly) ...
4
votes
3answers
388 views

How can we make compiling release notes less chaotic?

Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important ...
4
votes
2answers
88 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 ...
4
votes
3answers
81 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 ...
4
votes
1answer
102 views

Writing a PhD thesis. Question about (an informal) introduction

I am preparing scientific thesis for the degree of PhD. It is a mathematical thesis. It is usually very difficult to tell your colleagues and friends what are the things you exactly work on with ...
4
votes
4answers
768 views

When is a screenshot really useful in training documentation?

Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screenshots when the graphical ...
4
votes
2answers
148 views

Should subsection headings sometimes repeat section headings?

In a technical or scientific text, such as a PhD thesis, should headings for (sub)sections be complete and sometimes repeat information from the headings of the levels above, or is it sufficient to ...
4
votes
1answer
1k 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 ...
4
votes
1answer
347 views

singular or plural for index entries

I am in the final stages of writing a book and currently I am preparing the index. Are there any rules whether index entries should be listed in singular or plural? Currently I have Markov chains, ...
4
votes
1answer
195 views

How can I prepare for a career in instruction writing and editing?

To technical background authors (e.g. Isaac Rabinovitch) who would possibly work in teams with non-technically trained writers: How can I prepare myself to be able to do what you do? How can I ...
4
votes
1answer
3k views

How to write time duration correctly

Within a user manual, I need to convey the maximum time period allowed as "365 days 23 hours 59 minutes 59 seconds" - are commas expected between each component? Is the word "and" expected before the ...
4
votes
1answer
226 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 ...
3
votes
7answers
1k 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 ...
3
votes
5answers
4k 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 ...
3
votes
3answers
430 views

Best way to write an article professionally

Is there any widely accepted step by step method for writing a creative article in a professional manner. I want to improve my English writing skills in relation to creative article writing. I read ...
3
votes
3answers
319 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" ...
3
votes
1answer
115 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 ...
3
votes
4answers
71 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 ...