Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.
12
votes
5answers
579 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 ...
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 ...
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 ...
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
180 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
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
5answers
158 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 ...
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 ...
1
vote
1answer
154 views
Using Glossary Instead of Footnotes (for translation/transliteration)
I am writing a technical report with keywords which are mainly English. I am using a Glossary at the end, which describes translated keywords. Is it a replacement for footnotes or I should just keep ...
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 ...
4
votes
3answers
457 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. ...
2
votes
1answer
635 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
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 ...
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 ...
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 ...
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 ...
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 ...
3
votes
5answers
220 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 ...
1
vote
4answers
129 views
How can I express this more clearly or concisely?
I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems ...
1
vote
1answer
633 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 ...
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 ...
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 ...
3
votes
1answer
111 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 ...
2
votes
4answers
86 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 ...
6
votes
2answers
271 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, ...
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 ...
3
votes
1answer
232 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 ...
49
votes
13answers
4k views
What's the modern way to handle gender in tech writing?
Back in my day, I was taught to use masculine pronouns.
The user chooses a password, and then
he types it in the text box.
I'm fine with that. but a male coworker insists on using he/she, ...
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 ...
2
votes
3answers
217 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 ...
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 ...
9
votes
6answers
930 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 ...
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 ...
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 ...
5
votes
6answers
444 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' ...
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 ...
4
votes
3answers
487 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
3answers
273 views
8
votes
13answers
961 views
Does a technical writer need a technical background?
Does a technical writer need a technical background?
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?
5
votes
2answers
191 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
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 ...
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 ...
4
votes
5answers
223 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 ...
-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, ...
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
7answers
631 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 ...
