Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.
2
votes
1answer
78 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
votes
0answers
31 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 ...
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
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 ...
0
votes
2answers
50 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 ...
5
votes
4answers
235 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
118 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 ...
4
votes
4answers
92 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 ...
-1
votes
1answer
52 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
1answer
73 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
120 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
116 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
539 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
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 ...
2
votes
1answer
110 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 ...
-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 ...
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. ...
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
312 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 ...
10
votes
6answers
318 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 ...
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 ...
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 ...
0
votes
1answer
80 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 ...
3
votes
1answer
100 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
2answers
377 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 ...
2
votes
3answers
132 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" ...
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 ...
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 ...
9
votes
4answers
366 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 ...
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?
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 ...
5
votes
2answers
150 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
3answers
115 views
How to leverage social proof?
How can one use social proof as an argument without sounding like "just because everybody is doing it so should you"?. My problem is trying to demonstrate with social proof that trendy ...
0
votes
1answer
77 views
Giving something an alias
Within a technical document I want to refer to a system or process by a shorter name. I have no idea what this process is called so searching the internet is not getting me anywhere.
Is this correct?
...
0
votes
1answer
88 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 ...
5
votes
3answers
180 views
How can you write less to say more?
Sometimes you can write a lot without saying anything, sometimes you can say a lot but get little through the reader.
In technical writing the later is very typical (at least for me), one can tend ...
3
votes
3answers
444 views
What would sections of a book that are larger than a chapter be called?
I'm writing a technical book, and I want to split my book up into about 3 to 6 very broad sections, each of which would have several chapters in it. Is there a standard name for these broad pieces ...
0
votes
1answer
322 views
What are the names of the different levels of English?
In a recent discussion regarding software manuals, we came across the issue of different styles of writing / speaking in English. I am having a hard time finding a list of the different styles, such ...
2
votes
3answers
103 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
6answers
279 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
287 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 ...
1
vote
4answers
136 views
Where to find authors for highly technical articles?
I've looked at some of the largest outsourcing sites. These have huge amounts of software developers, and huge amounts of casual writers. I'm having enormous difficulty finding authors that would be ...
1
vote
3answers
122 views
How do I use my blog as a platform for practice and improvement?
I've recently followed the advice of our very own Jeff Atwood and started a blog site in order to become a better writer and communicator.
My goal is to improve my skill at technical writing and ...
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 ...
4
votes
1answer
227 views
Is there a style / terminology guide for Android OS application documentation?
This relates to my earlier question: My first professional writing job: any advice?
I will be involved with writing documentation for an Android OS business application. Is there an Android style ...
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 ...
4
votes
1answer
188 views
What tense to use in an academic paper when speaking about correspondence?
What is the correct tense to use in an academic paper when speaking about correspondence? Say one of my source materials is a letter written by someone named William, in which he says he went to the ...
5
votes
2answers
448 views
Should I prefer long or short sentences in scientific writing?
Currently, I am writing papers with rather short sentences: About half of them contain around 20 words, about 10% to 20% even less. I am doing this for three reasons:
I find short sentences easier ...
