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

learn more… | top users | synonyms

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 ...
4
votes
4answers
171 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
2answers
744 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
1answer
184 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
52 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
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 ...
4
votes
1answer
422 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
2answers
58 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
140 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
204 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 ...
4
votes
1answer
179 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 ...
3
votes
5answers
221 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
6answers
684 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 ...
3
votes
3answers
179 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
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 ...
3
votes
4answers
68 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
3answers
220 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 ...
3
votes
3answers
997 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 ...
3
votes
2answers
117 views

Present tense in user manuals

I am writing a user manual for an IT system. And inside the user manual I have sentences such as: Users can delete Servers that do not have Customers assigned to them. Is the use of ...
3
votes
1answer
2k 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 ...
3
votes
3answers
136 views

How to leverage social proof?

How can one use social proof as an argument without sounding like "just because everybody is doing it so should you"?. My problem is trying to demonstrate with social proof that trendy ...
3
votes
3answers
540 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 ...
3
votes
3answers
50 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) ...
3
votes
2answers
71 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 ...
3
votes
1answer
167 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
1answer
306 views

What is the style used in ISO/IEC publications?

I'm in the process of preparing a document to be sent to ISO/IEC WG14. What is the official style used in ISO/IEC publications (if there is one)? If there is no official style guide, is there a ...
3
votes
3answers
88 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 ...
3
votes
1answer
879 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 ...
2
votes
7answers
827 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 ...
2
votes
2answers
180 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 ...
2
votes
3answers
118 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 ...
2
votes
2answers
103 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?
2
votes
3answers
117 views

Thesis writing: how to address “self”

This came up when I was writing my thesis: Usually it is recommended that when writing a thesis, one sticks to passive voice and use sentences that read like "The study showed the effect that blah ...
2
votes
1answer
68 views

Can I use the same figure twice in a report?

Is it alright to use the same figure twice (but different figure number) in a report? If so, do I have to use separate captions, to avoid confusion in the table of figures?
2
votes
2answers
1k 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 ...
2
votes
3answers
136 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 ...
2
votes
3answers
267 views

Should Game Genre Types Be Capitalised?

I am currently writing a report for college about computer games and I am wondering whether genres need to be capitalised. Usually I do not but for some reason it just feels that I should. For ...
2
votes
4answers
82 views

How to reference a figure from text in a technical document

I'm preparing technical documentation for some software. For the installation, there are lots of screen grabs and they all have Figure x captions. What's the correct styling and means of referencing ...
2
votes
4answers
88 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
1answer
96 views

Resources for thesis writing

Will be writing my master's thesis in a few months. I have never written a thesis yet though. I was unlucky enough not to be required to have a thesis during my undergrad years. Anybody know some good ...
2
votes
1answer
205 views

In what narrative mode should you explain a process or task?

I want to explain a psychological and behavioural process to someone via email. I start off in first-person and speak to them in second-person, but what do I use when I want to explain a process ...
2
votes
2answers
207 views

List of figures and diagrams?

I was wondering what is the most acceptable way of including a large diagram in my thesis. The diagram takes up a full page and splits a paragraph. In your opinion is this bad? Should I put the ...
2
votes
2answers
170 views

API reference doc: best practices for describing opaque parameters?

The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool ...
2
votes
1answer
69 views

Metrics for assessing the persuasiveness of a paper?

Are there any known variables to measure, or questions to ask in survey, in order to asses the persuasiveness of a paper? For example, I'm not sure if omitting a section from my paper might actually ...
2
votes
1answer
102 views

How to combine a visual and textual outline

I am a Ph.D. student in engineering, so most of my writing fits into a fairly strict idiom: the IMRaD (Introduction, Methodology, Results, and Discussion). In general, I like to use an outline to help ...
2
votes
1answer
125 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 ...
2
votes
4answers
148 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 ...
2
votes
1answer
1k 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 ...
2
votes
1answer
149 views

How should be the format for literature references that are websites (URLs)?

In technical writings are good established standards for formatting literature references. But that doesn't work this well for URLs. How should these references be formatted?
2
votes
1answer
101 views

Can Google Docs be used for technical product documentation?

My company is hiring a contract technical writer to improve our product's documentation. As the maintainer, I'm currently using Google Docs, and very happy with it's collaborative nature (multiple ...