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).
477
questions
7
votes
5
answers
161
views
Why do many manuals and technical documents seem to prefer passive voice?
It seems like many manuals and technical documents prefer passive voice over active voice. Is this true, or is it just my perception? If so, why?
8
votes
2
answers
187
views
What strategies are there to document data lineage and keep it updated with a minimum amount of maintenance?
Quickly communicating data lineage to other stakeholders in our organization has become increasingly difficult as we scale.
What are effective strategies to address this and keep it maintained?
An ...
- 516
6
votes
1
answer
380
views
Is markdown a good choice for large-scale, web-based software developer documentation?
"Markdown" has become very popular for people creating developer documentation due to how easy it is to learn compared to most alternatives. Unfortunately there are dozens of "flavors" of markdown and ...
- 516
28
votes
6
answers
771
views
How much humour is effective in technical documentation?
It's well known that live presenters are often advised to add a dose of humour in order to engage the audience better.
However, I very rarely see humour in written technical documentation; this ...
- 578
25
votes
9
answers
157
views
Should beta functionality be mentioned in a training manual?
I write training manuals for a software product. When that product is next released one of the tools in it will be marked "in beta". i.e. that functionality is is included only as a technical preview.
...
Mark Ireland
12
votes
4
answers
364
views
How can I ensure that my documentation is understandable both for native and non-native speakers?
In short: When writing documentation that will be read both by Anglophones and non-native speakers of English who have various levels of language proficiency, how do I make sure that both these ...
user23425
16
votes
7
answers
2k
views
How do you explain the details of something technical to a non-technical audience?
When writing about technical topics it is often difficult to get across the complexity of a topic without getting "stuck in the weeds" and ultimately leaving the audience confused or disinterested. ...
- 725
4
votes
1
answer
3k
views
Can tables describing data go into the materials and methods section?
I have a table that describes a dataset that I use for an analysis. The table describes the sample sizes of each of the four collecting events to create the dataset. It breaks down the dataset into ...
- 43
7
votes
2
answers
157
views
Is writing "Bad practice"-notes in tech guides bad style?
So, I'm in the process on writing a hardening guide for Windows 10.
Similar to http://hardenwindows10forsecurity.com/index.html, but different in scope and style.
I wondered, if informing about "Bad/...
- 73
1
vote
2
answers
128
views
Q about verb tenses for technical writing
This kind of thing comes up a lot in my engineering job. We're writing a document that is a Plan for something we'll be doing in the future. For instance, a Test Plan that describes who will ...
- 13
4
votes
1
answer
3k
views
Citing Oracle documentations of Java
How can I properly cite an Oracle's documentation of the usage of certain APIs?
For instance
HashMap - Oracle Documentation
I need to cite/reference this in my research paper, what is the best way ...
- 143
0
votes
1
answer
102
views
How to write a doctoral thesis? [closed]
A few days ago I attended a seminar titled "How to write your doctoral thesis?". I was not able to follow all the points during the seminar. However, the most remarkable ones are easily conceivable.
...
- 143
3
votes
2
answers
93
views
How do I include two prerequisite ideas without a non-sequitur?
This question is about scientific writing. Scientific projects often bring together a problem from one field and an approach from another. When it comes time for me to write about the project, the ...
- 133
1
vote
1
answer
127
views
There will be vs There is : When writing proposals for IT projects [closed]
Please read following two sentence.
There will be around 20 reports.
There is around 20 reports.
What is the correct / most suitable one?
4
votes
2
answers
504
views
Do I always need to use linkers and connectors?
I have a question on linkers and connectors. I'm from Spain, so I learnt English at school and all my English teachers have told me throughout secondary school that we always have to use linkers to ...
Arnau
4
votes
2
answers
244
views
Present tense or Future tense (When writing articles or technical guides)
Should we use present tense or future tense when writing an article? I know this question will be off topic if I asked without example. So I will add an example:
You should use a very clean font ...
3
votes
3
answers
207
views
How to draw the line between expository and argumentative writing?
I am a secondary school teacher. My school requires teachers to focus on teaching argumentative writing during one quarter and informational, expository writing during another.
While discussing plans ...
- 353
3
votes
1
answer
48
views
Can I publish an erratum to add a reference to another author?
I would like to know if it's possible to add an erratum for my own book just to mention/reference a blog post from another author.
I just forgot to add a reference and I think it's important to add a ...
- 31
1
vote
2
answers
193
views
How to ask a question and define what I mean?
I am in the middle of the painful process of buying a car. I am trying to do much of my legwork online before going into a dealership. One of the things I hate the most about purchasing a car is ...
- 247
4
votes
2
answers
55
views
Indexing: after or during the writing process
I use Latex for writing articles/papers/longer documents. Most of these documents are scientific in nature, and therefore it is often useful to add an index of the most important terms at the end of ...
- 173
7
votes
1
answer
354
views
Can I publish a book containing content licensed under the GNU Free Documentation License version 1.2?
I'm writing a book and I'd like to include text that I found under the GNU Free Documentation License, version 1.2
I have no problems attributing the content to the source, but I don't understand the ...
- 173
2
votes
1
answer
76
views
What are the advantages of publishing an RFC
I am considering submitting an RFC article to publish here. However, I would like to know if there are any advantages that I gain if my article gets published other than bragging rights.
Thanks.
- 125
3
votes
2
answers
145
views
Referencing Screen shots in technical/knowledge base articles?
when writing knowledge base articles to support software users - is it ok to reference the screenshots I am using with the term "Figure"? For example, using '(See figure 1)' in the body text when ...
6
votes
1
answer
131
views
Considering the audience for technical publications
At work we provide three types of technical document, aimed at different kinds of users :
The Quick Start Guide. Single laminated sheet, illustrations and basic explanation.
The handbook. A5 format ...
10
votes
5
answers
298
views
In searchable documentation, what function does a glossary serve?
I work (with a team) on a large documentation set for a complex software product. We publish HTML and have built-in search (plus, of course, there's Google).
The doc set has a glossary, which ...
- 21.4k
2
votes
3
answers
190
views
How to transmit feelings in a technical book writing?
For example, in Skype conversations you use emoticons. I might use (headbang) after a phrase to express frustration, or I can have a (facepalm) moment, or I can write a joke and add (rofl), etc.
But ...
- 21
3
votes
2
answers
275
views
Is active or passive voice more common in scientific writing?
I am choosing between two sentences:
We display the values of X in Table 1.
The values of X are displayed in Table 1.
The first is more action-oriented, the second is more passive but focuses on the ...
- 133
0
votes
1
answer
93
views
Text formatting
Hello everyone! I want to know how to format text to something normal as depicted in the image. How can this be done quickly? Thank you for your time!
- 13
3
votes
1
answer
376
views
Framemaker 2017 and change bars
I have a document that is +2k and it’s all tables. I use change bars to track changes.
Q – Does FM note what changed when it assigns a change bar? Do I always have to use 'Track Changes'? In Word, it ...
4
votes
2
answers
545
views
In a formal syntax notation, how should I indicate many optional elements?
We use a BNF style to convey syntax for SQL statements. For a (fictitious) example:
CREATE PARSER [schema.]function
[WITH [LANGUAGE='language']
[, MODE='[FENCED | UNFENCED]'
[, STUFF='...
- 21.4k
14
votes
5
answers
2k
views
Acronyms in Technical Writing
I can't find a standard, is the most common use to have the abbreviation followed by the defintion?
Example
NATO: North Atlantic Treaty Organization
- 229
1
vote
0
answers
71
views
Attribution of authorship within group reports in academia [closed]
I teach a senior design course for undergraduate engineering students at a public university. Our senior design projects are all team based, usually with three to five engineering students per team. ...
- 111
4
votes
3
answers
172
views
Presenting documentation for a large software product
My documentation team supports a massive software product, over 30 modules. These modules are individually licensed, so one customer might pay for all the modules where another might only pay to use a ...
- 41
1
vote
1
answer
69
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 ...
- 13
7
votes
1
answer
188
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. ...
user24004
10
votes
3
answers
270
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 ...
- 355
3
votes
3
answers
958
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 ...
- 151
4
votes
5
answers
724
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 ...
- 151
3
votes
1
answer
319
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 ...
- 21.4k
2
votes
1
answer
296
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 ...
- 85
1
vote
2
answers
962
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). ...
- 21.4k
3
votes
1
answer
174
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 ...
- 131
1
vote
3
answers
187
views
When to not use SI symbols for units?
In the book What If?, the author usually writes the units out as kilometer, atmosphere, megawatt instead of km, atm, MW. However, he does use the symbols in the drawings:
In one line, both mm and ...
- 381
2
votes
1
answer
330
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 ...
- 208
2
votes
1
answer
249
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 ...
- 21
1
vote
1
answer
296
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 ...
- 11
1
vote
1
answer
83
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 ...
- 113
2
votes
2
answers
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 ...
- 81
1
vote
1
answer
10k
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
...
- 111
3
votes
1
answer
129
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 ...
