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
0
votes
0answers
23 views

How to write useful and respectful comments and remarks on academic thesis, papers and other proof-read stuff to motivate and valuable author's work?

You are probably familiar with this situation: I spend weeks or months writing something and then give it to someone for proof-reading. When I get it back, some remarks bother me or annoy me. ...
0
votes
1answer
17 views

Section headings: “to check…” vs. “checking”

I have a technical document which consists of the following sections: 1. Assignment statements 2. Concatenation 3. Data types 4. To check whether key exists 5. To retrieve value 6. To check whether ...
3
votes
1answer
66 views

How to list main ideas in a conclusion chapter without being repetitive with the wording?

In the conclusions chapter of my book (technical, non fiction writing) I want to go over the main ideas I addressed throughout the entire book, as a reminder for the reader and really drive in some of ...
0
votes
0answers
14 views

ShareLaTeX or OverLeaf templates to write a book to be self-published on Amazon

I'm planning to write a book and eventually self-publish it online through amazon (I haven't decided which platform on Amazon yet, but Kindle seems reasonable). The book will contain mostly texts, but ...
1
vote
1answer
24 views

Zero-that clause (noun clause with that)

After omitting "that" from a that-clause, is the clause still dependent? Or, does doing this turn it into an independent clause? For example: Before: "I suggested that she not go there." After: "I ...
1
vote
1answer
33 views

Methodologies to organise writing/copy/editing tasks

This question is all about methodologies to handle the workload efficiently for a freelance who deals with copy/editing of documents/articles. In my branch (IT development) we have Agile Methodologies ...
3
votes
4answers
103 views

How do I avoid using punctuation inside quotation marks in technical writing?

As a computer programmer, I comment my code. For example: The following lines are dependent on "source 1" and "source 2". "Source 2" is a user login and password. Overall, the purpose is to ...
-1
votes
1answer
46 views

What software do they use to create textbooks or board game manuals? [closed]

I'm wondering if there is some free software in which I could quite easily compose a book with a lot of images, something like textbooks for children for learning foreign languages (an example: https:/...
2
votes
1answer
36 views

mentioning verbatim sentence of another research

Is it possible to use a verbatim sentence of another research in our own studies? I, as an undergraduate psychology student who doesn't have any research experience, have heard that this is not ...
1
vote
2answers
57 views

Book recommendation for keeping writing specific / concrete

My job requires formal writing, however after self-review, I found that my writing does not have enough substance. This was confirmed as feedback from higher-ups implied that I use too many phrasal ...
1
vote
0answers
24 views

How do you quote a quote? [duplicate]

There's this sentence from Marie Kondo’s book, The Life-Changing Magic of Tidying Up: The Japanese Art of Decluttering and Organizing that I want to use as a title of my project, and I'm not sure if I ...
0
votes
2answers
62 views

Past or present tense when describing a well-known method in the description of an experiment?

I am describing an experiment for a scientific paper. In this experiment, I use a very well-known technique which I briefly describe, similar to the following variant (#1): In this experiment, we ...
0
votes
1answer
42 views

Is “and” or “or” better in this sentence?

When I was writing a manual, I wrote a sentence like example no.1 below. Is it natural to use an "or" like the bolded ones in the sentence? Or it is better to use "and" like example no.2? 1 You ...
1
vote
2answers
94 views

How do you transcribe a person's tone (i.e. someone whose speech is rude and/or attacking)?

I've been having great difficulty with transcribing an individuals "tone" in my meeting notes!! For context: Recently I've been charged with transcribing an incredibly tense litigious meeting. My ...
1
vote
1answer
38 views

When to write (see Section …) or simply (Section …)?

I am writing a technical paper and would like to refer to a previous section in brackets. I have seen it done both ways: Things are like this and that (see Section ...). Stuff is stuff (Section ...). ...
0
votes
0answers
31 views

Constructing a standardized form for a collection of technical manuals

I've been reading several articles about the use of voice within technical writing (both passive and active) and would like feedback and guidance on the proposed content structure. Use Case I plan ...
2
votes
2answers
38 views

Can MS Word perform single-source help authoring?

My company is using Microsoft Word to manage thousands of documents that ultimately end up publishing only to a couple outputs: primarily PDF but also some web and we're moving toward an app. We need ...
-2
votes
1answer
55 views

Software or Softwares [closed]

It seems to me that softwares is incorrect. I am of the opinion that software is partitive. I try to use some software or piece of software. Do you think it is incorrect to say softwares?
-3
votes
1answer
60 views

What is UX writing? [closed]

What is UX writing? I am a writer and a UX designer by trade. I hear a lot about UX writing being the next big thing. Should I specialize in this area?
7
votes
1answer
2k views

Can you legally write a book based on technical concepts that someone else’s coined?

Is there any issues with writing a book and publishing it that is based on topics and concepts that the technical industry previously coined? Several books have been written on the topics, I just ...
4
votes
1answer
47 views

What to do when API objects and UI names are different?

This question is in reference to API documentation. Say the name of an object is "Action" in the backend, but "Step" in the UI. We cannot rename objects. My approach is to explain that Action = Step ...
1
vote
1answer
22 views

How to reference Other Sections in a document

I am writing a procedure and want to reference other sections in the same procedure. What is the correct way to call them out? Example: The xxxx are shown in Section V, Procedures Used to Implement ...
1
vote
2answers
32 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 ...
2
votes
1answer
64 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
99 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
96 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: Include ...
4
votes
3answers
108 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
130 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
41 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
721 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
85 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
79 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
99 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 ...
3
votes
1answer
84 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
163 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
129 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
100 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
123 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
107 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
287 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
95 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
301 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
973 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
357 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
84 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
69 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
108 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?

1
2 3 4 5
9