Writing Stack Exchange
Writing Stack Exchange

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

For questions specific to software documentation, see .

500 questions
97
votes
17 answers

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 I find needlessly distracting and complicated. I…
Lynn Beighley
  • 3,209
  • 2
  • 22
  • 27
64
votes
12 answers

What's the least distracting method to inform editors I'm a woman?

I have a gender-neutral name, so people often assume I'm a man. However, a portion of the writing I do is for tech companies. Because of the lack of diversity in the tech industry, many of these companies are looking to add diversity to their…
Morgan Meredith
  • 1,002
  • 1
  • 7
  • 19
43
votes
7 answers

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 writing training. The longest thing I have ever…
Nodey The Node Guy
  • 533
  • 4
  • 6
37
votes
7 answers

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 how to use something. (I'm specifically talking…
Sharon M
  • 738
  • 5
  • 11
33
votes
7 answers

Is there a hemisphere-neutral way of specifying a season?

I want to refer to the timeframe of Summer 2019 in the Northern hemisphere. However, the writing is intended for a global audience, and when it is Summer in the Northern hemisphere it will be Winter in the southern hemisphere. Is there terminology I…
Jimmy
  • 441
  • 4
  • 5
31
votes
10 answers

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 than the intended audience is used to. I already…
HedgeMage
  • 4,485
  • 1
  • 23
  • 38
31
votes
5 answers

How to construct a technical tutorial when the user can't verify the results after each step?

In a technical tutorial it is helpful for a user to be able to check their progress often. Veryfing that the steps have produced a result is good because the user: has a feeling of progress can check for any mistakes they've made However, I'm…
user23425
28
votes
6 answers

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 despite it also being widely known that most people…
DVK
  • 578
  • 4
  • 12
25
votes
9 answers

Should beta functionality be mentioned in a training manual?

I write training manuals for a software product. When that product is next released one of the tools in it will be marked "in beta". i.e. that functionality is is included only as a technical preview. Product documentation will surely include that…
Mark Ireland
24
votes
2 answers

When documenting Python, when should I use docstrings and when should I use comments?

Python programming language provides two mechanisms for documenting a function, a module or a class: Comments and Documentation strings (or Docstring). Both can be accessed by reading the source code, but the latter is also available by calling…
DYZ
  • 383
  • 2
  • 10
23
votes
5 answers

When writing an error prompt, should we end the sentence with a exclamation mark or a dot?

When writing an error prompt, should we end the sentence with a exclamation mark or a dot? I am writing an application for iPhone and I have some error prompt in my application like "Your password must be 8 character long with alphanumeric…
user36239
22
votes
7 answers

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 showing only the relevant excerpts from the sample…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
22
votes
9 answers

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 in English class at school, something that's…
Will Appleby
  • 320
  • 2
  • 7
21
votes
12 answers

Can basic grammar rules be skipped when writing text for machine safety labels?

First of all I'm completely against this idea but a few people who contribute to the technical documentation project constantly suggest that to attain a short, quick, economic, comprehensive message some basic rules can be broken. Things like…
Montag451
  • 433
  • 2
  • 6
  • 24
20
votes
5 answers

Writing a programming book: how to present directory structures

What is good/preferred way of presenting directory trees in programming books? My main criteria are following: It should be readable and intuitive It shouldn't take too much page space It shouldn't require too much effort from author to create…
Piotr Sobczyk
  • 303
  • 1
  • 2
  • 5
1
2 3
…
33 34