Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

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

1
vote
1answer
38 views

Permission to use open source data

I am working on a technical book teaching users how to analyse data using geographic information systems. I would like to use data from an open source data portal such as open source fire department ...
1
vote
2answers
81 views

How can I get a technical writing job for software apps without a degree? [duplicate]

I have no degree and I cannot afford to have one, however, I would really love to get into technical writing because I love writing and I am interested in web and software development. Right now, I am ...
3
votes
4answers
50 views

How can I mention errors in the data that I received in my thesis? Where to mention it?

I received data for data analysis for my Bachelor-Thesis. I still got 4 weeks left to finish the 40 pages and after having gotten all my results, my supervisor and I realized that the data that I ...
7
votes
3answers
325 views

What would a FtM transman's, who was born in 1990, life be like? [closed]

I am writing a story with a trans character (female to male) set in the 1990's. My main character's parents are supportive from the beginning, but did transpeople have access to hormone injections and ...
2
votes
0answers
37 views

Comparing writing style and clarity of instructional language [closed]

Background: I am comparing a historic set of procedural instructions for the same action see mini-corpus below (1770-now). I have noticed that almost all are in the active voice but the older ones ...
7
votes
3answers
270 views

Difference between DITA and S1000D

I'm trying to understand the technical difference between DITA and S1000D. Yes, I know, the common wisdom is that if you need documentation for helicopter or submarine, you should use S1000D, and if ...
6
votes
2answers
179 views

Topic-based authoring vs. Modular authoring

What is the difference between "topic-based authoring" and "modular authoring"? As I know, there are two well-known authoring approaches: Narrative authoring; Topic-based authoring (see link above). ...
1
vote
0answers
110 views

I have a retracted article for ethical misconduct, this means my career is over? [closed]

When I was in my first year of M.SC. A professor told me to work on a project that the main data were belong to him. He had sent me a early draft and told me to translate it to english so I did along ...
5
votes
1answer
110 views

How do I insert programming code snippets within Scrivener?

I'm trying out Scrivener, as I intend to write some technical material. I'm a Software Developer and what I intend to write is programming related. I still wasn't able to figure out how can I insert ...
28
votes
5answers
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 ...
3
votes
1answer
71 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? ...
7
votes
1answer
70 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 ...
5
votes
6answers
202 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
2answers
91 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 ...
6
votes
2answers
98 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. ...
9
votes
2answers
70 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 ...
12
votes
2answers
158 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: ...
4
votes
2answers
108 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 ...
14
votes
4answers
3k 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 ...
6
votes
4answers
98 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 ...
21
votes
8answers
2k 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 ...
5
votes
2answers
72 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 ...
4
votes
4answers
98 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 ...
3
votes
2answers
69 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 ...
2
votes
2answers
102 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 ...
3
votes
1answer
37 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 ...
5
votes
1answer
96 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 ...
11
votes
2answers
938 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 ...
3
votes
1answer
48 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:...
0
votes
2answers
523 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
10
votes
3answers
1k 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 ...
3
votes
2answers
62 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 ...
17
votes
3answers
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 ...
36
votes
7answers
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 ...
6
votes
4answers
19 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 ...
11
votes
3answers
90 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 ...
8
votes
1answer
66 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
3answers
90 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 ...
8
votes
4answers
36 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 ...
7
votes
2answers
83 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 ...
8
votes
4answers
37 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 ...
9
votes
3answers
68 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 ...
14
votes
5answers
84 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 ...
57
votes
12answers
18k 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 ...
6
votes
3answers
209 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
3answers
121 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 ...
9
votes
5answers
13 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 ...
3
votes
2answers
16 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 ...
9
votes
3answers
16 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 ...
14
votes
3answers
52 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 ...