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
1answer
63 views

presenting a plethora of technical parameters in a thesis

I'm writing my masters thesis at the moment. The topic of my thesis is the evaluation of one classification algorithm. Due to its technical nature I have to give a lot of context for each experimental ...
7
votes
1answer
179 views

Technical Writing Other Than Software

There is a lot of advice on how to be a tech writer for software without a tech background. (That is, skills such as understanding end-users, investigative reporting-type skills to probe experts, etc. ...
10
votes
3answers
252 views

Documenting the no-args call of a command line program

I am writing the built-in help for a command line program. The exact name is irrelevant, so let's use foo as a placeholder. This utility can be called with some arguments (like foo -v) or without any ...
3
votes
3answers
908 views

Metaphors and other "tricks" in scientific papers

In scientific papers (in my case it's usually in computer science) it seems to me that some techniques which help in explaining concepts and technology are not used that much. For example a metaphor ...
4
votes
5answers
612 views

How much detail when writing technical documentation?

As a software developer, I often find myself writing my own technical documentation and user guides. How much detail should be put into this documentation? When is it too much detail? EDIT I'm ...
3
votes
1answer
299 views

How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen?

We use doxygen to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual tool of choice for Java APIs is Javadoc, but doxygen can do both and we ...
2
votes
1answer
258 views

MLA Background Research Paper: Noting a citation in the text?

I need to write a background research paper on a science fair experiment, but it needs to be formatted in MLA. I looked up some examples of a MLA essay and research paper but there seems to be ...
1
vote
2answers
900 views

Can we use MadCap Flare with semantic markup?

My team uses MadCap Flare to produce a large body of documentation (thousands of topics). The source is "Flare HTML", HTML with some Flare additions (for variables, admonitions, snippets, and so on). ...
3
votes
1answer
156 views

How to quote programming code in AP Style?

I would like to put the following code in an article that is written in AP Style: puts 'Hello, world!' How do I do this? If I were to put the code (C++, Ruby, whatever) in an article that was ...
1
vote
2answers
131 views

When to not using SI symbols for units?

In the book What If?, the author usually write the unit as kilometer, atmosphere, megawatt instead of km, atm, MW. However he does use the symbols in the drawings: In one line both mm and millimeter ...
2
votes
1answer
323 views

How does one evaluate his own writing ability?

I'm considering working in writing. I'd like to save myself some time in case I'm not up for the job. How do I go about evaluating myself as a professional writer? I was going to ask for a peer ...
2
votes
1answer
234 views

What are ways to automate documentation generation?

A lot of the documents we make at my work follow the same format; the document that takes the most time is, without getting into too many details, a report on a project that a client undertook. The ...
1
vote
1answer
281 views

How hard would it be to find writing jobs with an English degree?

I would love to work as a technical writer, copy editor, journalist, or whatever--as long as it's related to writing. I would especially love to freelance and complete contracts every day. So, I've ...
1
vote
1answer
77 views

When to evaluate whether your book will sell?

For a new guidebook project (freelancing in IT) I wonder at which point I should evaluate the idea. I see these possibilities: Create a website with a newsletter subscription form and see if people ...
2
votes
2answers
4k views

Runbook template example?

I have been searching for a Runbook / Operations Guide example and can't seem to find a useful one for my company. The current runbook they handed me contains use cases and requirements, which I know ...
1
vote
1answer
8k views

How to replace "and/or" in sentences with multiple terms?

When writing a legal document, what is the proper way to replace and/or in a list with more than two terms to remove ambiguity? For example, if I just have two terms: deliver apples and/or oranges ...
3
votes
1answer
107 views

Typographical styling of UI text in document

What are the usual typographical conventions to set off text from the UI in a user manual? For example, how should I style the text of the label on a button in: Press the Submit button. Or ...
3
votes
2answers
190 views

How to keep documents with example full date timeless

I am writing a corporate guidelines manual. The manual itself is made in InDesign, and contains sample documents in it that show employees how to correctly write/format despatches. These documents (...
1
vote
1answer
182 views

How to make a sentence seems more legitimate? [closed]

I have the following sentence: Earn Up to $12,000 for Evaluating Code! I am thinking of using this as a headline to entice visitors to enter their email, but most people feel this sentence scares ...
8
votes
7answers
505 views

Will I ever be able to write like a native writer?

So a little while ago someone said that I'll never be able to write on a native level because I wasn't born in the UK or America. I did, however, go to elementary school in the US at the ages of 5-10 ...
11
votes
2answers
205 views

How to clarify the objects of a sentence's two pronouns?

I am trying to describe a process. There are two players in the scenario. Player A tries to find player B. If player A finds player B, then player A tags player B. Something like that. Here is an ...
4
votes
4answers
121 views

How to move back to main section after finishing a sub-section

I am writing a paper but I don't know how to move back to the main section after I'm done writing a sub-section, like this: 1.1 Main section 1.1.1 subsection 1 1.1.2 subsection 2 As I write long ...
10
votes
2answers
695 views

Starting a sentence with the name of a program or command-line tool: capitalization?

Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you ...
3
votes
1answer
667 views

How to structure the text when describing the steps of a procedure which has simultaneous processes?

I have to further explain my intent here. I'm writing down some procedures in operating manuals and servicing manuals. I mostly use numbered lists and sometimes just bulleted lists. Recently I started ...
1
vote
1answer
94 views

How to communicate multiple meaning in a sentence more concisely?

Good day everyone, I have the following sentence: Around 70% of small businesses in the United States struggle to hire qualified employees, and around 50% attribute this challenge to ...
3
votes
1answer
102 views

How do I announce an area-restricted feature without discouraging the rest of my visitors?

I want to make an announcement to my users at my website about a new feature launch. However, in its first phase, this new feature has limited access - it will be supporting only one city for now, and ...
4
votes
1answer
108 views

How to communicate two elements of different general syntactic/semantic type in the same sentence?

I have the following sentence, NAME is a community that helps each other code better by rating each other's efforts and helps managers pair with other fellow developers I was suggested by the ...
20
votes
12answers
6k views

Can basic grammar rules be skipped when writing text for machine safety labels?

First of all I'm completely against this idea but a few people who contribute to the technical documentation project constantly suggest that to attain a short, quick, economic, comprehensive message ...
6
votes
3answers
481 views

Should I use contractions in a technical tutorial?

In a technical tutorial which fits better: In this tutorial you'll learn or In this tutorial you will learn or in general does it make no difference?
0
votes
1answer
549 views

How can I rewrite the sentence for technical writing style [closed]

I want to rewrite my sentence in technical writing style. Could you help me rewrite my sentence? Thank you in advance The proposed methods has 4 variables need to update in a optimization process, ...
0
votes
1answer
180 views

Referring to a diagram

In a math book, should I write "diagram 3" or explicitly "diagram at the figure 3", when referring to a diagram in a displayed figure? (The title of the figure (as autogenerated by LaTeX) is "Figure 3....
7
votes
4answers
1k views

Web-based WYSIWYG Markdown editor with commenting?

My question is similar to this one, but with (hopefully) a clearly defined use case: sharing and reviewing basic tech docs with a minimal, intuitive GUI. I'm producing technical documents using MS ...
0
votes
2answers
138 views

I am writing a book on web design. What elements should I remove to avoid copyright issues?

I am writing a book on web design, titled Best website design. I will list photos of some good-looking portfolio websites in the book. Do I need to take permission from the website owner? Will it be ...
6
votes
2answers
137 views

Is there a standard for describing a form in a programming specification?

I'm a web programmer at a small web firm. When we have a larger programming project, I write a specification document for the client to review, make necessary changes, and eventually approve. Our ...
0
votes
1answer
148 views

Requirements engineering: getting the most out of Word?

Are there any features in MS Word (ideally for Mac) that can be helpful in requirements gathering/tracing? As an example, at present I'm using comments in the Review pane to index requirements and ...
16
votes
11answers
2k views

Can technical writing suck less

I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider myself a reasonably proficient ...
-1
votes
3answers
842 views

High Tech Audience

I have to write a simple introduction on the topic HTTP and its audience will be high tech. I am having a bit of problem in how to describe it in high tech audience? Can any one would suggest me how ...
1
vote
3answers
105 views

How do you write a good product description? [closed]

Are there any rules or procedure to write a great product description. Any examples of good desciptions online?
1
vote
1answer
3k views

should I put the reference number after the dot or after a space? [duplicate]

I am writing my thesis. and I need to know the correct way of putting the reference. for example: this is a sentence taken from someone [2]. this is a sentence taken from someone[2]. this is a ...
2
votes
1answer
67 views

Should I use figure titles for diagrams on the web?

Should I use figure titles for diagrams in web content if the diagram already has a caption? Guidance or references are appreciated. The context is a marketing page whose basic structure is shown in ...
2
votes
1answer
162 views

Ways to influence the readers subconscious?

Are there any proven techniques of influencing the readers on a subconscious level? Preferably techniques involving only words as I'm interested in writing technical books and I don't have the liberty ...
4
votes
2answers
447 views

Plural of single letter variables

Excuse me if I am on the wrong StackExchange site. I write about Physics in English and typeset that with LaTeX. So I have a variable c, and there are two of them in the same expression. I want to ...
4
votes
2answers
131 views

Attracting and retaining volunteers to edit technical doc for open source projects

I volunteer as an editor for the Mozilla Developer Network (MDN), an organization that creates free open source software such as the Firefox browser. MDN has a large number of technical topics ...
2
votes
1answer
86 views

Concepts for more interesting introductions in papers

What are the key concepts for writing introductory text more interesting to the reader? An example: The Deutsche Bahn AG is the company with the most energy consumption in Germany. It has ...
1
vote
3answers
94 views

Should you emphasise text within quotation marks?

e.g. Bold: Click "Setting" then click "Options". Italic: Click "Setting" then click "Options". Or even underline? Or none quotation marks? Click Setting then click Options. Which is ...
4
votes
3answers
2k views

How can I avoid using the first person in a report when directly referring to work and experiences I have had?

I have been asked to write a report on the company I am working at during a placement from University (I am on an engineering programme). There was not much guidance given on what the content of the ...
1
vote
1answer
50 views

APA Headings- Frequency

How often should you use a heading? Are there any guidelines or limitations to using headings too often (i.e., every paragraph, every other paragraph, etc.)?
3
votes
3answers
1k views

Use of the Oxford comma

The oxford comma is the second comma in the sentence I like the colors red, white, and blue. Every grammar textbook I've ever seen, as well as the major style guides, feels that this is "proper" ...
1
vote
2answers
212 views

How I should handle gender-neutral pronoun in technical writing? [duplicate]

I am writing API documentation for a mobile loyalty program and I am not sure which of the following is better wording: 1) When the user requests for their visit and order to be registered in their ...
4
votes
1answer
3k views

How to reference an ISO/IEC?

I'm doing some college work and I'm using ISO/IEC 27000 Information technology — Security techniques — Information security management systems — Overview and vocabulary. In Word, I have set up the ...

1
3 4
5
6 7
9