Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.
2
votes
1answer
98 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 ...
5
votes
4answers
238 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, ...
0
votes
1answer
119 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 ...
-1
votes
0answers
32 views
Peter Abel biography [closed]
I have been reading a great and famous book IBM PC Assembly Language and Programming by Peter Abel. But I didn't find his biography or any info about him. Who know who is he in IT world? It's very ...
2
votes
1answer
79 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 ...
1
vote
1answer
57 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
53 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
50 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
53 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
93 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
75 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
121 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
119 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
567 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
112 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
900 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 ...
2
votes
2answers
56 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. ...
4
votes
5answers
223 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
64 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
121 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
94 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
315 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
280 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
76 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 ...
10
votes
6answers
321 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 ...
1
vote
1answer
62 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 ...
0
votes
1answer
81 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
87 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
387 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
444 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
962 views
Does a technical writer need a technical background?
Does a technical writer need a technical background?
1
vote
1answer
93 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
164 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
199 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
101 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 ...
2
votes
3answers
133 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" ...
2
votes
1answer
289 views
What is the best way to learn technical writing in English?
I have a moderate level of skills in technical writing in English (TWE) having gone through graduation in engineering. I was wondering what would be the best way to sharpen my knowledge. I am also ...
9
votes
4answers
374 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
154 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
459 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
154 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
111 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
104 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 ...
3
votes
5answers
220 views
How can this technical message be made clearer?
How could this technical sentenced be improved for better clarity?
Cannot translate the ‘name1’ concept1 to the ‘name2’ concept2 because the higher
precedence ‘name3’ concept3 also exists, which ...
2
votes
2answers
87 views
What are “industry leading royalties”?
In the breakdown description I received from a publisher, they mention that they also pay industry leading royalties of ##%.
What does that mean?
