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).
497 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
63
votes
12
answers
19k
views
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 ...
- 992
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 ...
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
33
votes
7
answers
8k
views
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 ...
- 441
31
votes
5
answers
4k
views
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 ...
user23425
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
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
25
votes
9
answers
213
views
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.
...
Mark Ireland
24
votes
2
answers
5k
views
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 ...
- 383
23
votes
5
answers
5k
views
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 ...
user36239
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
22
votes
7
answers
3k
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 ...
- 21.5k
21
votes
12
answers
6k
views
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 ...
- 433
20
votes
5
answers
13k
views
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'...
- 303
19
votes
9
answers
7k
views
Should one use the legal "shall" in requirements documents and specification documents?
At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of ...
- 587
19
votes
6
answers
338
views
Should technical writers illustrate their own documents?
In my opinion, visual material is of crucial importance in technical documents, especially in procedures, but paradoxically, technical illustrations seem to be a dying art.
Is it better for a ...
Federgraf
17
votes
14
answers
1k
views
Is it okay to call the reader's target audience stupid?
I'm a tech genre author, and have already published one book on Android development. However, this book was focused more on the developer of the apps, than the user.
Now I'm working on my second book,...
- 273
17
votes
3
answers
10k
views
In academic writing why do some recommend to avoid "announcing" the topic?
In academic writing, several articles on the topic of writing papers denounce the practice of "announcing" the topic.
As an example, if a paper were to read...
The goal of this study is to not be ...
- 281
17
votes
4
answers
8k
views
Where do I start with C++ documentation?
I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly beneficial. My question is not how to add ...
- 4,471
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
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
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
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
15
votes
4
answers
2k
views
How can I make a case for toning down the "rah rah" marketing tone around technical content?
Summary
Starting from the position that -- with modern web delivery -- the line between technical communication and marketing content is fading (as all the content is available to business and ...
- 738
15
votes
3
answers
1k
views
Should IKEA assembly instructions be used as positive examples to train technical writers?
Often, assembly instructions are bad (example via Adafruit):
But they don’t have to be: writing assembly instructions is a skill that can be learnt, and there are institutions which teach it.
IKEA ...
- 505
15
votes
3
answers
56
views
How to make documentation accessible to vision-impaired audiences?
Nowadays, governments and corporations alike are putting an ever-increasing number of accessibility laws in place to ensure that disabled audiences are not put at a disadvantage. How can technical ...
- 351
15
votes
1
answer
79
views
To what extent should domain terms be capitalized?
Some terms in technical documentation, for example product proper names, should obviously be capitalized. But there are other terms that are somewhere between a proper name and a generic noun: domain ...
user23425
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
14
votes
10
answers
4k
views
Is it overkill to follow style-guides for technical writing?
I currently work for an engineering company as an electrical engineer. A good chunk of my time is spent writing testing reports or instruction documents. Currently my company doesn't have any sort of ...
- 243
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
14
votes
8
answers
4k
views
Which is more readable - array of ints or int array?
A similar example is field of carrots or carrot field.
The latter feels better to me, especially in the carrot example, but when asking colleagues they preferred 'array of ints'.
I'm not a ...
- 251
14
votes
2
answers
1k
views
Preferred word for "preferred", "target", "chosen" in end user support documentation
I'm having trouble finding and sticking to one word to indicate whatever value the user intends to use with my instructions.
For example:
Select your preferred printer.
I'm wondering what ...
- 291
14
votes
6
answers
4k
views
When is a screenshot really useful in training documentation?
Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screenshots when the graphical ...
- 245
14
votes
3
answers
715
views
Instruction manuals: should the end-user be addressed directly (passive vs imperative)?
Manuals come with virtually any appliance, and they typically target the end-user.
Among other things (legal specifications, part numbers…), these documents contain specific instructions on what to do ...
- 505
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
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
12
votes
8
answers
831
views
What are standard techniques that indicate to the documentation reader that they are to substitute their own appropriate text (e.g. username, domain)?
When reading manuals or guides, I can easily get confused between what is meant to be example text, and what is actually meant to be used.
For example, sometimes the username to login to use a ...
- 245
12
votes
4
answers
443
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
12
votes
4
answers
2k
views
Personal or impersonal in a technical resume
In CVs or on Linkedin profiles there are often spaces dedicated to past experience.
In those sections, one is supposed to describe what work he/she did and what skills he/she acquired on previous ...
- 15.9k
12
votes
4
answers
425
views
Can "numbers" be good doc performance metrics? Is there a way to meaningfully interpret the quantitative user data we gather?
I work on developer documentation at a tech startup. As of now, we implement the following feedback mechanisms:
We have a thumbs-up/down feedback system on each page of the docs site. If a user ...
- 129
12
votes
3
answers
2k
views
How to effectively document a product composed of complex microservices?
I have a highly flexible software product consisting of a series of loosely coupled microservices. Each component is effective at a single job, but may be dependent on inputs from other services. It ...
- 477
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
3
answers
1k
views
Why are license agreements, disclaiming letters and others written with capital letters?
We know that reading sentences with capital letters is hard.
I noticed that some documents are still written with capital letters.
Why are license agreements, disclaiming letters and others written ...
- 221
11
votes
10
answers
362
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 ...
- 213
11
votes
8
answers
4k
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 ...
- 491
11
votes
6
answers
11k
views
Demo data in screenshots! What are the best practice?
My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making ...
- 111
11
votes
2
answers
1k
views
Structure for software documentation: long vs short pages
For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more ...
user23425
11
votes
2
answers
980
views
Starting a sentence with the name of a program or command-line tool: capitalization?
Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you ...
- 213