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

learn more… | top users | synonyms

12
votes
5answers
678 views

Best practices for maintaining documented code examples?

A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically ...
1
vote
3answers
267 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
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 ...
5
votes
2answers
646 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
384 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
2k 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
796 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 ...
7
votes
2answers
133 views

How do you track dependencies for your co-authors?

I and one or more co-authors, sometimes geographically distributed, are working on a set of related documents. Sometimes I will make a change in my part that has effects on someone else's part; this ...
10
votes
3answers
230 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
58 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
58 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
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 ...
5
votes
5answers
143 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
65 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
122 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
149 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 ...
5
votes
6answers
268 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
281 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
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 ...
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 ...
10
votes
6answers
1k views

Technical Writing Software

I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such as ...
6
votes
4answers
404 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 ...
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 ...
5
votes
3answers
845 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?
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
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 ...
1
vote
2answers
164 views

What free tools are there to help me improve my English?

I am in the process of writing a research paper in Computer Science. Are there any free tools/browser plugins/web sites/latex plugins that would help me improve my English? I am looking for some nice ...
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 ...
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 ...
10
votes
5answers
2k views

How much time do you spend writing one page on average? [closed]

I'm writing a technical book about one programming technology and would like to compare how much time other authors spend on one page (on average). I rarely write a page and am done with it, quite ...
5
votes
3answers
307 views

Is the idea of single-sourced documentation dead?

Is the idea of single-sourced documentation dead?
7
votes
3answers
473 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?
5
votes
2answers
214 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 ...
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 ...
6
votes
8answers
455 views

Verbosity: when's enough enough?

In corporate life I've come across two general styles of writing: terse and cryptic or long and complete. In my own writing I tend to go too much in the "explain all possible interpretations" ...
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?