Stack Exchange Network

Stack Exchange network consists of 175 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).

0
votes
0answers
39 views

Company under investigation [on hold]

If a company that you’re working on is being investigated by the police, what will happen? Will the company be suspended for the time being that it is under investigation? Or will it still continue ...
3
votes
2answers
65 views

When writing an error prompt, how do we tell the user the error happens in a specific tab?

https://en.wikipedia.org/wiki/Tab_(interface) I have made a medical record application that allows someone to record data about someone, but the application also allows us to add the data of a ...
21
votes
5answers
4k 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 ...
2
votes
1answer
58 views

Copyright related issue on publishing a technical book?

I am preparing to publish a technical book on programming that contains figures and charts (like, compiler, linker, ASCII table, keywords list) created by myself by taking references from many sources....
6
votes
1answer
97 views

Does software exist to easily markup technical documents as audio scripts?

Inspired by this question: Is there a need for better software for writers? I have an IDE¹ related question about software that can assist writers. Is there a tool to (easily) turn technical ...
1
vote
2answers
65 views

What are the recommended sizes for a text box?

If I am making a text box for an online document, how many characters should I leave for things like names and dates?
10
votes
4answers
1k views

What is a more techy Technical Writer job title that isn't cutesy or confusing?

I have been hired as a Technical Writer at a firm who needed multiple types of writers: A few people were hired to write content for the average website reader interested in our product, such as a ...
6
votes
2answers
49 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 ...
4
votes
1answer
68 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 ...
8
votes
1answer
272 views

Plain language with long required phrases

I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader. Some of our conventions require us to always use the full phrase as ...
32
votes
7answers
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 ...
4
votes
5answers
2k views

Shortening a title without changing its meaning

Essentially, I want to change: Managing a lot of people is a very difficult problem to: Lot of people, difficult problem I understand that when you shorten a title, it will become more vague, ...
5
votes
2answers
72 views

For HTML documentation sets, are there meaningful guidelines for topic length?

We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics -- ...
4
votes
1answer
69 views

Is it ok to use long footnotes?

In my text, I have a footnote (6 or 7 lines) that is meant to be an extra insight. It does seem, however, to be a bit large for a footnote. On the other hand, if I try to place it inside the text, ...
4
votes
3answers
53 views

What is special in API documentation compared to general technical writing?

The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?
12
votes
4answers
1k 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 ...
7
votes
3answers
56 views

How to include external references when writing internal documentation?

In the IT industry, we often write a lot of technical documentation meant for internal use only. Those documents are often stored in an internal wiki and accessed when the need arises. The content ...
5
votes
2answers
77 views

Documenting software requirements

As a self-taught developer the only requirement documents I've ever been privileged to read are those of hackerrank and the sort. However the more and more I create my own increasingly complex ...
2
votes
1answer
96 views

What should go into a White Paper?

I've heard the term "white paper" used in many situations. I've been asked before to write white papers on different subjects, though I've never successfully completed one. I've read many different ...
9
votes
2answers
94 views

How do we write a good edit on Wikipedia?

Is there a way to make sure that what we write sounds consistent with the style adopted by the majority of editors? I am not sure how people do it, but almost all articles seems to have been written ...
3
votes
3answers
52 views

Terminology in sociology & statistics

What is the word commonly used in statistics when the thing that you want to measure cannot be (or was not) measured directly, so you assume that another thing that can be (or was) measured gives an ...
4
votes
3answers
67 views

What is in scope for criticizing technical writing

I'm not well versed in technical writing. I'm probably not going to be in a position to give anyone feedback for some time, but I would like to know how to approach it when I get there. I would also ...
9
votes
4answers
407 views

How to tag distinct options/entities without giving any an implicit priority or suggested order?

An example of the problem in an aggravated form surrounds the controversy of France changing ‘mother’ and ‘father’ to ‘parent 1’ and ‘parent 2’ in official paperwork - where the controversy suggests ...
2
votes
0answers
18 views

Is there any room in technical-writing for levity [duplicate]

When doing technical writing it is generally advised to be straight to the point. And I understand that. After all if I am reading instructions on how to put together the desk I just bought, or how to ...
7
votes
3answers
773 views

Methods for writing a code review

I currently spend a good deal of time over at Code Review and I would love to improve the quality of the reviews I write. Can you give me any insight into the structure or approach you use when ...
7
votes
2answers
66 views

Strategies for writing software design documents

I'm a self-taught programmer which means I started writing software by sitting down at an IDE and hammering out some code. When my decisions ultimately coded me into a corner I would refactor and ...
10
votes
4answers
922 views

How to know you are over-explaining and oversimplifying a subject?

Recently, I started writing articles about different subjects I learn on my own (programming, logic ...etc). While writing, I have this tendency to overexplain, I know that readers are smart, but I ...
4
votes
2answers
120 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 ...
2
votes
2answers
97 views

What's the correct way to write 3 x 10^6 (three million)?

I am reviewing some research reports and found myself diving into the black hole of technical writing style. My question is what is the best way to write numbers in millions? I am not writing a ...
8
votes
4answers
135 views

Sentence starters for summaries?

I'm writing a technical book (step-by-step sort of book) and noticed that all my summaries start with 'In this chapter we ...'. What would be some other sentence starters that I could use to make the ...
1
vote
1answer
30 views

Dots in lists with mixed-width items

It is common to omit end-dots in lists with very short items: Shop list: * Milk * Bread * Probably eggs It is common to use end-dots in lists with long descriptive items: Things which should be ...
2
votes
1answer
82 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
155 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
101 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 ...
2
votes
0answers
56 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 ...
8
votes
3answers
544 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 ...
7
votes
2answers
673 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
148 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
730 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
88 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? ...
8
votes
1answer
89 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
279 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
176 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
136 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
96 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
269 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
125 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
4k 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
112 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 ...