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

Filter by
Sorted by
Tagged with
5
votes
1answer
87 views

Technical specification for webservice (developers-oriented) - examples, methods & instruments

Good time of the day, community! Hope, that my post won't irritate too much, but rather will be helpful for someone in future. I already made some progress myself (I mean some raw unfinished version ...
3
votes
2answers
279 views

Job description for my employment reference

I've canceled my job to move on. Now I was asked how I want my Job description for my employment reference. My first draft was one full page... This is too much. Now I've reduced the long version to ...
6
votes
1answer
84 views

In scientific writing, what is the protocol for shortening nouns?

I often see place or species names shortened in scientific journal articles and would like to know what the correct protocol is. Can I shorten "Gough Island" to just "Gough"? Or "leatherback turtle" ...
8
votes
5answers
183 views

What are some standards in naming a software/hardware version?

I am wondering if how we name a version of a spacecraft differs from how we name a version of a software. For software, I usually see things like "2.0.32.32" or something like that and sometimes they ...
15
votes
2answers
956 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 ...
3
votes
2answers
65 views

What are the indentation rules for the paragraph introducing a bulleted list?

I'm writing a formal document for my company where it'll be shared and used by a number of teams. Unfortunately, we don't have any official standard style guide to follow, so I've attempted to be as ...
3
votes
2answers
73 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 ...
22
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
64 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....
5
votes
1answer
102 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
67 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
53 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
92 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
279 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
79 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
77 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, ...
6
votes
4answers
104 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
68 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
86 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
106 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
100 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
55 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
75 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
411 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
21 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
779 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
73 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
956 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
127 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
101 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
142 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
33 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
161 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
113 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
653 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
826 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
871 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
89 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
90 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 ...
6
votes
6answers
307 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
199 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
138 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. ...