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

learn more… | top users | synonyms

5
votes
2answers
218 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
398 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
3answers
260 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 ...
4
votes
1answer
440 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
118 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
5answers
1k 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 ...
4
votes
3answers
144 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
5answers
292 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
199 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
874 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
198 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
80 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
62 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
144 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
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 ...
4
votes
1answer
618 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
76 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
182 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
215 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
184 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
510 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
4answers
113 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 ...
3
votes
3answers
234 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
6answers
925 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
212 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
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
2answers
2k 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 ...
3
votes
3answers
1k 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
1answer
3k 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
656 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
85 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
90 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
231 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
349 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
263 views

When is a screen shot 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 screen shots when the ...
3
votes
3answers
185 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
1k 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
984 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
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 ...
2
votes
2answers
359 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 ...
2
votes
2answers
120 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
147 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
167 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
3answers
142 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
306 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
170 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
92 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
290 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 ...