Questions tagged [technical-writing]
Documentation, tutorials, training, user guides, installation guides, design documents, and all other types of technical documentation in any domain (not just software).
58 questions
97
votes
17
answers
11k
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, which ...
- 3,199
43
votes
7
answers
4k
views
Writing first programming book
I was recently asked if I was interested in writing a book for a pretty reputable publisher, which of course I accepted. I am not a writer by trade, I am a software developer with some technical ...
3
votes
5
answers
961
views
Struggling to writing in English
I always struggle to write my ideas in English. Structuring my work/idea when it comes to writing leaves me blank.
Even when I'm very clear about what I want to write, I will still struggle with ...
- 33
13
votes
3
answers
750
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 ...
- 231
8
votes
8
answers
2k
views
How can I stop overusing "I" in my writing?
I won't edit this question, so you can see how much I use it. The current count is 3 times. I've been told that the solution is to revise, revise, revise, but is there a particular strategy for ...
7
votes
4
answers
2k
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 ...
- 235
2
votes
5
answers
789
views
Where can I go to have my writing reviewed both in terms of style and technical content?
I would love to have essays reviewed both in terms of quality writing and in terms of its content. I have researched a few sites but this service does not seem to exist.
2
votes
3
answers
457
views
Copyright of examples used in books?
I'm getting into non-fiction technical writing (a blog, but potentially ebook or otherwise). Often the best technical advice come from dissecting and synthesising good and bad examples from the ...
- 129
2
votes
2
answers
254
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 ...
- 121
28
votes
6
answers
908
views
How much humour is effective in technical documentation?
It's well known that live presenters are often advised to add a dose of humour in order to engage the audience better.
However, I very rarely see humour in written technical documentation; this ...
- 578
22
votes
9
answers
5k
views
How can I improve my sentence construction or flow in general writing?
Can anyone suggest resources or techniques I can use to improve my sentence construction when writing? I am a native English speaker and fairly well educated, but confess I didn't pay much attention ...
- 320
15
votes
4
answers
6k
views
In end user documentation, should screenshots come before or after the text that references them?
The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions or conceptual explanations of the software.
...
- 253
14
votes
11
answers
3k
views
Can technical writing suck less
I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider myself a reasonably proficient ...
- 2,094
11
votes
6
answers
2k
views
Ways to improve your writing skills
As a CS major I've learned that knowing how to write is critically important, but, I'm not really sure how to improve my writing skills. I'm currently trying to write a tech blog in English, but, ...
- 213
8
votes
4
answers
2k
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 ...
- 203
8
votes
4
answers
3k
views
How can I write better code-based reference documentation for programming interfaces?
Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what ...
- 21.5k
6
votes
4
answers
545
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 ...
- 21.5k
5
votes
5
answers
3k
views
Technical writer degree with an English BA?
I'm desperately trying to get out of my dead end Federal job. I have a BA in English and a love of a lot of different topics, including several science fields. I would have Majored in science if I ...
- 51
5
votes
1
answer
299
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 ...
- 267
5
votes
3
answers
656
views
How can we make reviewing HTML documentation easier?
Summary: I'm looking for a way for reviewers to comment collaboratively as close to "inline" as possible on a large HTML project.
The problem in detail
I work on a team that documents a ...
- 21.5k
4
votes
2
answers
1k
views
Use of Registered trademark
I'm writing a book on Windows and I need some guidelines.
On the cover of the book, as part of the subtitle, may I include Windows® in it?
Inside the book, do I have to use the ® every single little ...
- 41
37
votes
7
answers
6k
views
Should software product release notes be in marketing voice or technical voice? (software documentation)
Typically, the voice of marketing content doesn't match the voice of technical content -- marketing is trying to persuade you that you need something; technical writing is generally instructing you ...
- 738
31
votes
10
answers
1k
views
How can one make technical issues more accessible to a non-technical audience?
Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc. Lately, I find that some of the topics I am trying to present are much more technical ...
- 4,485
17
votes
3
answers
2k
views
How should I document a product release with an inherently flawed design?
The deadline is looming and someone realizes the product can't be shipped without documentation. Once the product leaves the remit of the software engineers (who obviously only ever write wonderful ...
- 477
17
votes
10
answers
4k
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 ...
- 281
16
votes
7
answers
3k
views
How do you explain the details of something technical to a non-technical audience?
When writing about technical topics it is often difficult to get across the complexity of a topic without getting "stuck in the weeds" and ultimately leaving the audience confused or disinterested. ...
- 725
16
votes
5
answers
658
views
Does DRY (Don't Repeat Yourself) Apply to Documentation?
In programming, it's usually accepted that DRY code is better code in most situations.
Does this principle also apply to documentation?
I'm asking about the documentation output, not necessarily the ...
- 521
14
votes
5
answers
2k
views
Acronyms in Technical Writing
I can't find a standard, is the most common use to have the abbreviation followed by the defintion?
Example
NATO: North Atlantic Treaty Organization
- 229
13
votes
5
answers
12k
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 ...
- 271
12
votes
2
answers
1k
views
Case study headings
I'm going to be preparing several case studies for my company and I'm pondering what patterns to use for headings—both the case study title and headings within a case study.
I'd like the reader to:
...
- 263
12
votes
4
answers
444
views
How can I ensure that my documentation is understandable both for native and non-native speakers?
In short: When writing documentation that will be read both by Anglophones and non-native speakers of English who have various levels of language proficiency, how do I make sure that both these ...
user23425
11
votes
3
answers
338
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 affects someone else's part; this could ...
- 21.5k
10
votes
3
answers
2k
views
Good tools for writing (game) manuals and sourcebooks
As I had asked in another part of Stackexchange (didn't know about this part until some comments there) I'm writing manuals (mostly for computer games, but in addition to this also for tabletop games, ...
- 223
10
votes
3
answers
406
views
How to write to accommodate subsequent automatic translation
The texts I am writing will be translated by people who are not experts in the topic and in some cases by a machine with next to none human editing afterwards.
What strategies should I employ to ...
- 233
10
votes
3
answers
3k
views
Using LaTeX with publishers?
Background: Im working on a rather long instructional book, and have just started trying to use LaTeX. The book doesn't have any scientific notation in it, and most of the diagrams I made in other ...
- 363
10
votes
17
answers
5k
views
Does a technical writer need a technical background?
Does a technical writer need a technical background?
- 8,726
9
votes
4
answers
1k
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, ...
- 192
7
votes
5
answers
378
views
Why do many manuals and technical documents seem to prefer passive voice?
It seems like many manuals and technical documents prefer passive voice over active voice. Is this true, or is it just my perception? If so, why?
7
votes
3
answers
6k
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?
- 8,726
7
votes
6
answers
461
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 ...
- 173
6
votes
1
answer
312
views
Outlining for white papers
I used to write technical white papers on different technologies. There should be some rules for writing professionals, some home work that needs to be done. I have never gone through any professional ...
- 63
6
votes
2
answers
95
views
How should we plan for translations' space needs when designing diagrams that require text?
Our documentation set includes some diagrams where text is integral and can't be handled in callouts, like flowcharts and entity relationship diagrams. Our documentation is translated, so these ...
- 21.5k
6
votes
5
answers
485
views
How do I get rid of the tic of paired adjectives, predicates, etc.?
In technical writing, I have a tic of writing in pairs. Some examples from a recent piece:
"When you speak, be sure to be clear and concise."
"Face to face conversation is personal and private."
"...
- 161
5
votes
3
answers
14k
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 ...
- 51
4
votes
1
answer
111
views
How can we make images with (necessary) text more translatable mechanically?
Our documentation set includes some diagrams, such as entity relationship diagrams and flowcharts, where text is integral and cannot reasonably be handled in callouts. Our documentation is translated ...
- 21.5k
4
votes
2
answers
6k
views
Spell out numbers before times, days, months?
The general rule I follow is to spell out numbers < 10. Also when use numbers before measurement I don't spell out.
For example:
I bought nine apples
We need 5 mL acid for this reaction
How ...
- 211
4
votes
3
answers
4k
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 ...
- 1,805
4
votes
2
answers
556
views
in English, is it necessary to capitalize after a colon?
I've seen that each language has its own rules when using the colon. In Spanish, it's not needed to capitalize:
Los elementos incluyen: secado, lavado, etc.
In French is the same, and even they put ...
3
votes
5
answers
4k
views
What are the tool choices for producing technical documentation in PDF and web site ready HTML?
My company currently maintains our technical documentation (User's Guide) in Google Docs. With each release I produce a PDF that we host on our website.
Here are the features of Google Docs that work ...
- 185
3
votes
5
answers
2k
views
What is considered an acceptable length for a technical document?
I have written dozens of technical and requirement specifications, and edited dozens more in 8+ years of engineering. The largest I have drafted was perhaps 100 pages, but maybe 30-50% of it was ...
- 131