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
1
vote
2answers
28 views

Will I use “the” in that instance or leave it with no article? [closed]

If I'm given a choice, to put "the" or leave the word with no article, what's the better answer? The world helps in boosting young confidence. The world helps in boosting the young confidence. Thank ...
1
vote
0answers
32 views

Explicit scientific syntax for academic writing (like a programming language but for scientific reports and publishing)?

This is a project I am thinking of working on in the future. Is anyone familiar with attempts to codify and create an explicit syntax for reporting science? E.g. like you would have specific ...
2
votes
2answers
90 views

Referring to machines and sensors as “knowing”

I'm editing a technical text about autonomous systems. I feel the following sentence is anthropomorphizing a machine and also introduces some confusion because it can be easily misread as talking ...
4
votes
1answer
86 views

Add Comma After “official” in “official third-party documentation”?

I'm drafting an internal standard on internal documentation covering third-party products or services in my organization. Documentation covering third-party products or services SHOULD NOT: ...
4
votes
3answers
95 views

What's a good replacement for the phrase “best practice”?

In technical writing the phrase "best practice" is often used to suggest that something is more accurate than other things. However, that's often very subjective, requires specific context, and ...
2
votes
1answer
108 views

The excessive use of 'and'

The word 'and' is an indispensable conjoining tool in any form and discipline of writing. Although, a repetition of the word can make a paragraph too tedious to read, and it only lengthens a sentence ...
18
votes
3answers
6k 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 ...
4
votes
2answers
34 views

Subfigures in a figure, how to label?

So if I later refer to figure 2 (i) or figure 2 (ii) would it be better for the figure to be labelled as is Figure 2: Figure (i) shows cycle C? or Figure 2: (i) shows cycle C or Figure 2: ...
2
votes
3answers
715 views

Where can I go to have my writing reviewed both in terms of style and technical content?

I would love to have essays reviewed both in terms of quality writing and in terms of its content. I have researched a few sites but this service does not seem to exist.
0
votes
1answer
54 views

How to link paragraphs in essays and articles?

All I can find online is cohesion and coherence for paragraphs. But in a essay how can I link all the paragraphs. Any good methods for the university level. It would be great if I can find an ...
1
vote
1answer
76 views

Is there any other way to share information on a website apart from typical Blogging, YouTube or Podcast?

I have a website and I want to share content mostly related to security and technology but most of the time I myself don't feel like reading long paragraphs. I am thinking about if there's a unique ...
-1
votes
3answers
94 views

Springer or CRC versus self-publishing

I have an IT textbook that is about 120,000 words which was accepted for publishing at several very reputable publishers. My goal is to get the text out to as many people as possible. My secondary ...
0
votes
0answers
35 views

What is Documentation Design that I haven't already done?

I'm a contractor who has been working on a project (a developer guide website) for months with another contractor writer. We spent a lot of time: Interviewing end users Designing the deliverable (...
3
votes
1answer
82 views

Computer science academic conference paper using “randvar” instead of “random variable”

I am reviewing a computer science submission to an academic conference. The authors use "randvar" instead of "random variable" (as well as "logvar" instead of "logical variable"). I am wondering if, ...
5
votes
2answers
117 views

Documenting framework features and descriptions

We have written a custom software framework and it has grown to the point where we are ready for documentation. This documentation will be used by other developers to share knowledge. I am concerned ...
3
votes
2answers
53 views

Correct way of Citing References in a writing a Non-Fiction book?

I am trying to write a non-fiction book about summarizing core computer science concepts. I plan to self publish this book through the Amazon Kindle Direct Publishing program. My target audience ...
4
votes
4answers
93 views

How to eliminate standoff between “Lengthy” vs “Concision”?

Often while writing a software requirement/change-request documentation, I need to include the quoted requirements descriptively, the impacted modules, the changes provided both in UI and in logic. ...
5
votes
1answer
101 views

Do writers need a business bank account?

My question is simple: do writers need a business bank account? Or can they use a regular account for saving and declaring tax on their earnings? Further, do writers need to declares themselves a ...
5
votes
1answer
102 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
286 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
89 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
202 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
969 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
148 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
77 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
68 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
105 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
73 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
55 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
97 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
282 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
126 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
112 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
181 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
133 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
115 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
101 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
62 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
83 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
414 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
22 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 ...
8
votes
4answers
880 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
79 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
1k 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 ...