Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.
3
votes
3answers
115 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 ...
5
votes
5answers
157 views
How to write about things which depend on each other
I am writing a technical documentation about a product. Now problem is there are many interrelated and interdependent concepts. I am just confused how to put them in order. I mean if I talk about ...
0
votes
1answer
77 views
Giving something an alias
Within a technical document I want to refer to a system or process by a shorter name. I have no idea what this process is called so searching the internet is not getting me anywhere.
Is this correct?
...
1
vote
4answers
113 views
Is this description of my small productivity application clear enough?
I wrote a small productivity application, Tomate. Since I'm not a native English speaker, I'm afraid the description of the project may not be clear enough for potential users. Can you help me improve ...
3
votes
3answers
444 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 ...
1
vote
4answers
136 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
3answers
180 views
How can you write less to say more?
Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader.
In technical writing the later is very typical (at least for me), one can tend ...
2
votes
2answers
176 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 ...
4
votes
3answers
125 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 ...
6
votes
6answers
385 views
Quality of my blog writing
I came here from Jeff Atwood's blog where he mentions that writing a blog can clear your own internal thought processes and that you should take feedback about your writing so that you can improve. ...
1
vote
3answers
122 views
How do I use my blog as a platform for practice and improvement?
I've recently followed the advice of our very own Jeff Atwood and started a blog site in order to become a better writer and communicator.
My goal is to improve my skill at technical writing and ...
0
votes
1answer
322 views
What are the names of the different levels of English?
In a recent discussion regarding software manuals, we came across the issue of different styles of writing / speaking in English. I am having a hard time finding a list of the different styles, such ...
4
votes
1answer
226 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 ...
-1
votes
2answers
121 views
What help is there for a technical reseacher/writer that can't edit?
I've got a personal professional goal - I want to write a thesis, build a system, change the world. That's my way of saying that my thesis needs to be something I can develop into a functional system, ...
12
votes
5answers
577 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
228 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
188 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
448 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 ...
7
votes
0answers
146 views
How do you build good per-book *and* global indexes?
For our SDK, we generate individual documents (PDFs) and one big HTML doc set (CHM file) from the same Docbook source. Each book has an index, and the HTML version has an integrated index that is the ...
6
votes
2answers
270 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, ...
8
votes
7answers
733 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 ...
7
votes
1answer
1k 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
548 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 ...
5
votes
2answers
82 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
179 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
55 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 ...
4
votes
3answers
456 views
Does reading books help writing skills?
Just what the title says. I decided to improve my writing skills only for blogging purposes (for starters and no, it's not a part of new year's resolution). I am also not really good at writing (i.e. ...
1
vote
0answers
56 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
634 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
132 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 ...
1
vote
0answers
60 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
100 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
107 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
229 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
181 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 ...
1
vote
1answer
632 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
171 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 ...
9
votes
6answers
929 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 ...
2
votes
3answers
370 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 ...
6
votes
4answers
300 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
231 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 ...
4
votes
3answers
485 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
216 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
91 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
140 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
193 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
274 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 ...
9
votes
5answers
1k 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
273 views
7
votes
3answers
377 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?
