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).

Filter by
Sorted by
Tagged with
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 ...
Lynn Beighley's user avatar
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 ...
Nodey The Node Guy's user avatar
3 votes
5 answers
950 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 ...
B.B's user avatar
  • 33
13 votes
3 answers
718 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 ...
Chad Cooper's user avatar
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 ...
pentavalentcarbon's user avatar
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 ...
Stat-R's user avatar
  • 235
2 votes
5 answers
786 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.
Eduardo J. Sanchez's user avatar
2 votes
3 answers
443 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 ...
Pie21's user avatar
  • 129
2 votes
2 answers
252 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 ...
user1982's user avatar
  • 121
28 votes
6 answers
832 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 ...
DVK's user avatar
  • 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 ...
Will Appleby's user avatar
16 votes
4 answers
5k 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. ...
Matthew Rodatus's user avatar
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 ...
Michael B's user avatar
  • 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, ...
Wilbeibi's user avatar
  • 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 ...
DaveBall's user avatar
  • 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 ...
Monica Cellio's user avatar
6 votes
4 answers
536 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 ...
Monica Cellio's user avatar
5 votes
1 answer
297 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 ...
Pitarou's user avatar
  • 267
5 votes
3 answers
532 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 ...
Monica Cellio's user avatar
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 ...
Jemma Lewis's user avatar
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 ...
Joshua's user avatar
  • 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 ...
Sharon M's user avatar
  • 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 ...
HedgeMage's user avatar
  • 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 ...
Jason Fox's user avatar
  • 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 ...
Travis's user avatar
  • 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. ...
thesquaregroot's user avatar
16 votes
5 answers
619 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 ...
Scribblemacher's user avatar
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
Rachel's user avatar
  • 229
13 votes
5 answers
11k 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 ...
Borek Bernard's user avatar
12 votes
2 answers
855 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: ...
Tin Man's user avatar
  • 263
12 votes
4 answers
415 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 ...
user avatar
11 votes
3 answers
333 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 ...
Monica Cellio's user avatar
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, ...
Thomas E.'s user avatar
  • 223
10 votes
17 answers
5k views

Does a technical writer need a technical background?

Does a technical writer need a technical background?
Ralph Gallagher's user avatar
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 ...
elburzs's user avatar
  • 363
10 votes
3 answers
401 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 ...
user7610's user avatar
  • 233
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, ...
theonlylos's user avatar
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?
Ralph Gallagher's user avatar
7 votes
5 answers
261 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?
EJoshuaS - Stand with Ukraine's user avatar
7 votes
6 answers
456 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 ...
Adam Lewis's user avatar
6 votes
5 answers
479 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." "...
philosophyguy's user avatar
6 votes
2 answers
80 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 ...
Monica Cellio's user avatar
6 votes
1 answer
307 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 ...
gyansangrah's user avatar
5 votes
3 answers
13k 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 ...
Jewelya's user avatar
  • 51
4 votes
1 answer
103 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 ...
Monica Cellio's user avatar
4 votes
2 answers
545 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 ...
Alejandro Marcos Aragon's user avatar
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 ...
Pravesh Parekh's user avatar
4 votes
2 answers
4k 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 ...
Twisted Meadow's user avatar
3 votes
1 answer
1k views

What are best practices when writing technical descriptions?

Occasionally, in my job as an engineer, I write process descriptions of the technology we are selling. Those are part of commercial offers, intended to win the customer. Those are bundled with ...
mart's user avatar
  • 183
3 votes
5 answers
1k 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 ...
JSM's user avatar
  • 131