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).
477
questions
3
votes
1
answer
102
views
How could I improve my article writing? [closed]
I am a teenager and would like to know more about article writing. I was to write some articles someday. Should I be casual or formal? What POV should I use? How should I arrange the paragraphs? ...
- 31
8
votes
1
answer
132
views
Repository of My Academic Writing - Which License to Use?
I'm adding a repository containing selected academic papers I wrote. I'd like to add a license to this repository that works similarly to the MIT license (but for writing and not code), where others ...
- 235
8
votes
8
answers
1k
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 ...
5
votes
2
answers
361
views
How can you start writing multi-author collaborative book?
We are a group of people who want to write collaborative a book, but since we are based in different locations, how can we go on with our writing?
Can you suggest a writing tool that might help us ...
- 151
6
votes
2
answers
154
views
How to present an alternative without being negative about the other option? [closed]
Good day,
I have the following sentence:
Nowadays to reach the mass audience, you don't have to rely on
traditional media. Instead, you can embrace social networks such as
live video streams.
...
- 63
9
votes
2
answers
134
views
Is there a definition for formatting plain text documents like they are on TLDP.org?
Is there a formal specification for authoring plain text documents like they (mostly) are on http://www.tldp.org/HOWTO/text/?
If so, what is it called? Where is it documented?
I'm looking for a ...
- 193
12
votes
2
answers
711
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
4
votes
2
answers
159
views
Rewriting User Guides as Stories
I'm increasingly having to write User Guides as part of my job and I need routes to make this into a more interesting exercise.
Hence, I was actually looking for something completely different when I ...
- 7,713
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,451
6
votes
4
answers
3k
views
What are alternatives to "is that" as in "[something] is that [something]"?
I am writing a thesis and I frequently find my self using the phrase 'is that'.
For example: "The other feature that has been neglected is that the expert system would ..."
I have been told that ...
- 163
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
6
votes
2
answers
346
views
Technical review process when using FrameMaker
I'm an engineer. At my company, engineers seem to spend a lot of time reviewing technical documentation written by people who work in different offices and time zones. Part of the reason we spend so ...
- 163
4
votes
4
answers
190
views
Should creativity or eloquence in a technical document be removed during review?
I am working on churning out some technical documents, which are similar to a colleague's. I've copied some sections of his document as appropriate, and there are no concerns of plagiarism. His ...
- 213
3
votes
2
answers
121
views
Putting code examples in BSC thesis
I am writing my bachelor's thesis in software engineering. It is split into two parts: a theoretical part where I analyze existing literature, compare models and draw conclusions; and a part where I ...
- 133
3
votes
2
answers
217
views
What language should I write my programming blog post in? [closed]
My background
I'm a native French speaker and a software engineer, I studied in French and grew up speaking French.
My Question is: which language should I use for my technical blog posts?
On one hand,...
- 133
2
votes
1
answer
86
views
What is the best way to take a theorem from another paper?
I would like to include a theorem from a paper, say Alice et al. [12], in my own manuscript.
Which option is the most readable one?
Theorem 6 [[12]]. Every even number can be divided by two without
...
- 121
5
votes
1
answer
881
views
What's the best way to write (or rewrite) a math book?
I've been writing a book that has a fair share of geometric diagrams and equations. However, I am unable to make use of a computer for this and have been maintaining a journal where I manually draw ...
- 151
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
3
votes
1
answer
86
views
Is it necessary to always write a prefix to indicate a Part Number in technical writing?
I'm wondering if there is an accepted way to prefix part numbers in technical writing. What I have seen a lot in our documents is:
Reference the test part P/N 12345.
Or in a table or list of parts:...
1
vote
2
answers
25k
views
Best alternate sentence for 'Please let me know if any questions/comments' [closed]
I feel bored to have this in my all mails 'Please let me know if any questions/comments', any best alternate sentence would be helpful for me
- 13
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
3
votes
2
answers
77
views
Should the documentation of a known issue change dependent on the stability of a product release?
I am writing the release documentation for a software product and a design flaw has been discovered after the code has been frozen. Does the documentation describing this issue change if the product ...
- 477
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
37
votes
7
answers
5k
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
7
votes
4
answers
395
views
What is the difference between "accurate" information in a document and "believable" information?
As part of some research I am doing on measuring documentation quality, I have come across the terms "accurate" and "believable" as two separate dimensions of information quality.
But the differences ...
- 493
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
9
votes
1
answer
87
views
Have there been any studies indicating which software documentation practices save the most time during onboarding?
It's generally conceded that at least some documentation saves people time when "onboarding" to a new project. With that said, have there ever been any rigorous studies on how helpful various kinds of ...
9
votes
3
answers
125
views
How does web page writing differ from blog and article writing?
Yesterday I was talking with a client and he asked me to write web page content. I told him that I can write blogs and articles.
He suggesed that I should learn web page writing, but I searched on ...
- 93
8
votes
4
answers
1k
views
Linking documentation to Git commit comments
Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a format ...
user25452
7
votes
2
answers
485
views
How to write recommendation documentation?
I was asked to prepare an overview of an existing IT architechture and provide a document that consists of weaknesses analysis and suggestions on how each of the weak spots can be improved.
How to ...
- 173
8
votes
4
answers
369
views
Is it better to repeat steps listed elsewhere in a manual, or to refer the reader to where the steps are listed elsewhere in the manual?
We have a tool that we cannot replace that does not support single sourcing. As a result, with instructions that involve the same node, we either repeat the same dozen steps over and over, or refer ...
- 544
15
votes
3
answers
995
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
16
votes
5
answers
557
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 ...
- 511
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 ...
- 982
6
votes
3
answers
439
views
Formatting of Text in Technical Writing (Procedure Writing)
In a procedure, when describing a UI component, we use the bold font to represent UI components. We also match the text with the letter case of the UI component. But do we need to match the font style ...
1
vote
3
answers
400
views
What is the best description for this particular kind of building (and apartment arrangement - Central European style of building)?
I'm looking for the word to describe of a particular type of apartment building. I attached a picture to illustrate it.
It is a building that has several apartments on each story with an exterior ...
- 11
9
votes
5
answers
31
views
Where would I specify which user is required to run an administration command?
I work with a software product that has over 10 major components. The administration of most of these is done with the root user with one notable exception where they use a less privileged user for ...
- 544
3
votes
2
answers
44
views
Our team needs to automate many routine tasks. Can we use a single tool or do we need to use multiple ones?
Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using Sphinx, reStructuredText, Adobe Illustrator, and Visio.
Specific things we need ...
- 516
10
votes
3
answers
58
views
Problems with getting meaningful and actionable feedback from readers
As someone who doesn't get paid to write stuff nobody reads :), I'm always on the lookout for the best ways to collect meaningful and actionable feedback from my readers so I can improve the quality ...
- 493
14
votes
3
answers
534
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
7
votes
2
answers
144
views
How do I maintain effective documentation for different audiences while avoiding duplication?
I need to maintain documentation of the same system for different audiences. How do I avoid duplication while still being effective?
I have a publicly-available API, and I also have internal ...
- 173
12
votes
4
answers
417
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
5
votes
3
answers
386
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.4k
12
votes
8
answers
415
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
24
votes
2
answers
4k
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
8
votes
5
answers
1k
views
What is the best way to collect comments on a draft document that is out for review by stakeholders?
Draft technical documents can be reviewed by stakeholders. Stakeholders can be fellow practitioners, industry specialists, senior managers, regulators, and so on.
The purpose of a stakeholder review ...
- 499
19
votes
6
answers
291
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
7
votes
2
answers
111
views
How to handle bad source texts in technical translation?
In technical translation (e.g. of manuals), the quality of the source text often is not very high.
This concerns not only the language used, but also the structure of the whole document.
Should ...
- 505
15
votes
1
answer
66
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
15
votes
3
answers
49
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