Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.
5
votes
3answers
72 views
Demo data in screenshots! What are the best practice?
My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making ...
4
votes
2answers
43 views
In end user documentation, should screenshots come before or after the text that references them?
The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions for or conceptual explanations of the ...
1
vote
2answers
74 views
How to represent dependencies in outlines
The bulk of my writing consists of technical papers, reports, notes, and memos. Because of the mathematical nature of my work I spend a lot of time writing definitions, and it is very important that I ...
12
votes
6answers
354 views
Should one use the legal “shall” in requirements documents and specification documents?
At least in the US, "will" has replaced "shall" in most every context, with the notable exception of the "legal shall". Shall is used instead of will in legal documents to indicate a sense of ...
2
votes
3answers
63 views
Introducing the next sub-section or not?
I am writing my phd dissertation in a technical field and I have a question. When in the same chapter, I finish a section and want to connect it with the next section I am not sure what is better. ...
0
votes
1answer
131 views
To translate a novel with Westerner's point of view
I am an Easterner. I have been translating a novel, that is originally written in my native language, into English. During the process, I have also been learning about cultural things, meant to ...
6
votes
5answers
279 views
Ways to improve your writing skills
As a CS major I've learned that knowing how to write is critically important, but, I'm not really sure how to improve my writing skills. I'm currently trying to write a tech blog in English, but, ...
3
votes
1answer
89 views
How can I prepare for a career in instruction writing and editing?
To technical background authors (e.g. Isaac Rabinovitch) who would possibly work in teams with non-technically trained writers:
How can I prepare myself to be able to do what you do?
How can I ...
4
votes
2answers
340 views
What is the best way to learn technical writing in English?
I have a moderate level of skills in technical writing (TW) having gone through graduation in engineering. I was wondering what would be the best way to sharpen my knowledge. I am also interested in ...
9
votes
2answers
168 views
How do you build good per-book *and* global indexes?
For our SDK, we generate individual documents (PDFs) and one big HTML doc set (CHM file) from the same Docbook source. Each book has an index, and the HTML version has an integrated index that is the ...
2
votes
1answer
194 views
Mashery vs. Apigee
I was wondering if anyone could lend some advice as to the pros and cons between using Mashery versus Apigee for documenting an API? I have do some evaluating and have about 2 weeks to come up with a ...
1
vote
1answer
62 views
Multiple tasks and a step by step tutorial
To my knowledge step-by-step tutorials should have the form of a ladder, where you describe how to get to a place step by step– accomplishing a single task at the end. Is it possible to accomplish ...
0
votes
2answers
69 views
What are the advantages of different date formats in resumes and CVs?
I've seen a somewhat related question, but it doesn't answer my question quite right. Say you're writing an event that happened on a single day, and you need to put it in your resume or CV. So how ...
0
votes
2answers
51 views
What is the correct word/term that needs to be before the names of the maker of the project?
I am doing a project with one other person, we have finished the project
and we are working on a cover page.
We are not sure what to write out before our names, we have thought
of a couple of ...
-1
votes
1answer
57 views
What to name the parts of my thesis [closed]
I'm currently beginning to order/structure my master thesis, which will consist of quite some chapters.
I'd like to divide my thesis into parts (either 2 or 3).
Now I'm trying to decide how to name ...
4
votes
4answers
102 views
How can I consistently distinguish among tables, fields, and records in a database?
I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows).
I spend a lot of time discussing tables and ...
4
votes
1answer
82 views
singular or plural for index entries
I am in the final stages of writing a book and currently I am preparing the index. Are there any rules whether index entries should be listed in singular or plural?
Currently I have
Markov chains, ...
4
votes
1answer
123 views
How to get a programming book published
So I feel I'm a pretty good programmer in my area of expertise. Whats the process for writing a book about my niche and getting it published?
4
votes
3answers
122 views
How can I express this fragment more clearly and concisely?
For the 'who is this application for' section of an application user guide, I have the following alternatives, I'm not happy with either one. How can I convey both elements more clearly and ...
2
votes
2answers
729 views
Multiple authors in MLA header
I'm writing a group paper and I was wondering whether there's a correct way to list multiple authors at the top of the first page in MLA format. Normally the header would look something like:
My Name
...
2
votes
1answer
123 views
In what narrative mode should you explain a process or task?
I want to explain a psychological and behavioural process to someone via email.
I start off in first-person and speak to them in second-person, but what do I use when I want to explain a process ...
14
votes
14answers
911 views
Is it okay to call the reader's target audience stupid?
I'm a tech genre author, and have already published one book on Android development. However, this book was focused more on the developer of the apps, than the user.
Now I'm working on my second ...
4
votes
5answers
225 views
Using uncommon abbreviations
Something which I see all the time in (popular) science writing is the use of abbreviations to indicate concepts. For (a made up) example:
So when we're dealing with Anachronistic Meta Mechanics ...
-1
votes
1answer
67 views
Which sort of features are required for a text editor in order to improve efficiency and comfort during writing?
I hesitate between classical editors (like MS Office, Open Office) and online editors which provide more accessibility.
I would say that I'm looking a polyvalent text editor to write my thesis. I'm ...
1
vote
1answer
123 views
combining sentences
I want to say couple of this within one sentence. so my sub sentences would be:
We removed the vertical features from the classification process.
The removal of vertical features enhances ...
1
vote
3answers
96 views
The Best Title for my Skill Set [closed]
I'm about to branch off into the freelance world. I'm starting an LLC and I'd like some input on what I should title myself as the owner. For example "creative specialist" or "creative technician" or ...
2
votes
1answer
375 views
How to write time duration correctly
Within a user manual, I need to convey the maximum time period allowed as "365 days 23 hours 59 minutes 59 seconds" - are commas expected between each component? Is the word "and" expected before the ...
3
votes
6answers
296 views
Is it overkill to follow style-guides for technical writing?
I currently work for an engineering company as an electrical engineer. A good chunk of my time is spent writing testing reports or instruction documents. Currently my company doesn't have any sort of ...
2
votes
1answer
78 views
How to combine a visual and textual outline
I am a Ph.D. student in engineering, so most of my writing fits into a fairly strict idiom: the IMRaD (Introduction, Methodology, Results, and Discussion). In general, I like to use an outline to help ...
0
votes
1answer
84 views
Should this sentence be included in the Executive Summary?
I found some examples of good and poor example of executive summaries here. Everything seems fine but in one of them, they included this sentence -
"All calculations can be found in the ...
0
votes
2answers
90 views
Am I correctly referencing chapters which belong to the same book?
Looking for some help on how to reference chapters in a book inside of a booking I'm helping with.
Should I be capitalizing Chapters 3 and 4 and would referring to chapters simply by capitalized ...
2
votes
2answers
416 views
Are contractions antithetical to academic writing?
This question is very specific to academic writing:
I used the contraction "don't" instead of "do not" in some of the papers. Some of the reviewers mentioned that "don't" is not a formal style of ...
5
votes
6answers
447 views
Does this feel like natural English?
Although I'm pretty confident in my English, I'm not a native English speaker. I need to write a short introduction for a symposium; I'd like to know if you think this paragraph feels like 'natural' ...
8
votes
13answers
988 views
Does a technical writer need a technical background?
Does a technical writer need a technical background?
2
votes
1answer
95 views
What resources will teach me about the state of the art in technical writing?
I've been asked to modernize some technical documentation - user manuals in particular. I have some guidelines, but a lot of free rein to take it in whatever direction I think is worthwhile. Where ...
4
votes
1answer
167 views
Habits and routines for my first tech writing job
A Japanese company has offered me a gig helping translate an Android1 business application + documentation into English. Their staff will do a rough translation, and I will polish it into something ...
5
votes
4answers
202 views
How can a new writer make a realistic estimate of his work rate?
This question relates to my earlier question Habits and routines for my first tech writing job which I was told to split into two parts.
My first technical writing / translation gig starts soon. A ...
3
votes
1answer
103 views
Path to publishing a technical book
I'm 21 years old female from South India. I would like to publish a book which concentrates on any one latest computer technology. Now, I have completed my BE- Computer Science and Engineering. I'm ...
3
votes
3answers
138 views
What's the correct vocabulary for a web application tutorial?
I am writing a tutorial on how to use a specific web application and I don't know which verbs to use. Shall I use "click" for buttons? But what if the user doesn't use a mouse? Contrary to "normal" ...
9
votes
4answers
408 views
Writing a programming book: how to present directory structures
What is good/preferred way of presenting directory trees in programming books?
My main criteria are following:
It should be readable and intuitive
It shouldn't take too much page space
It ...
1
vote
1answer
159 views
Using Glossary Instead of Footnotes (for translation/transliteration)
I am writing a technical report with keywords which are mainly English. I am using a Glossary at the end, which describes translated keywords. Is it a replacement for footnotes or I should just keep ...
0
votes
1answer
89 views
website to publish article on high-performance cluster computing?
I am writing a tutorial-type article on high-performance cluster computing. It is aimed at researchers and grad students who want to use clusters to answer scientific questions, especially in the life ...
49
votes
13answers
4k views
What's the modern way to handle gender in tech writing?
Back in my day, I was taught to use masculine pronouns.
The user chooses a password, and then
he types it in the text box.
I'm fine with that. but a male coworker insists on using he/she, ...
1
vote
4answers
129 views
How can I express this more clearly or concisely?
I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems ...
22
votes
10answers
462 views
How can one make technical issues more accessible to a non-technical audience?
Most of what I write is non-fiction -- technical books, blog posts on open source topics, political stuff, etc. Lately, I find that some of the topics I am trying to present are much more technical ...
5
votes
2answers
164 views
Why are license agreements, disclaiming letters and others written with capital letters?
We know that reading sentences with capital letters is hard.
I noticed that some documents are still written with capital letters.
Why are license agreements, disclaiming letters and others written ...
3
votes
1answer
112 views
Which is a better composition?
Consider following sentence composed in different ways,
And the worst, when memory is full, creation of new node will return a NULL.
And the worst is when memory is full and a new node is created ...
2
votes
4answers
86 views
Advice on interface text in a videogame
[This fits somewhere between technical writing and user experience, so perhaps this is the wrong board]
I'm developing a modification to a popular videogame (a Playstation One RPG), with the ...
2
votes
3answers
106 views
Would it be weird if I write “a simple sample something”?
Not getting too technical, I am writing a configuration file for a piece of software I have developed. This software allows others to write "services" and attach them to my software.
I have written a ...
3
votes
4answers
61 views
In a “learn to do X” book, should a section review come before the quiz / exercises or after?
I am writing a book on how to program in C#.NET.
Each of the sections follows this format:
Section Aims
Content
Section Review
Quiz
Exercises
The section review is there to summarise all of the ...
