Posts tagged technical-writing
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 t...
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 tha...
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 b...
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 t...
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 th...
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...
In the breakdown description I received from a publisher, they mention that they also pay industry leading royalties of ##%. What does that mean?
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 tools/techni...
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 ...
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 easi...
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 t...
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 b...
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 kee...
Short version: What is an equally informative, but more interesting alternative to typical academic-article-style scientific writing? Longer version: I love writing, I do a lot of it – fiction an...
My employer has presented me with two books to read to help me write better technical papers and emails. Essentials of English Grammar and Handbook of English Grammar and Usage. I have read throu...
[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 expre...
I am currently writing a report for college about computer games and I am wondering whether genres need to be capitalised. Usually I do not but for some reason it just feels that I should. For exa...
I wrote a small productivity application, Tomate. Since I'm not a native English speaker, I'm afraid the description of the project may not be clear enough for potential users. Can you help me impr...
I'm creating some copy describing new web-app features for a number of different audiences (users, managers of sections of the site, owners of sub-sites which use our platform etc.). I'm finding m...
For those that are just starting out, what are key skills they should have or learn to be a good technical writer?
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 Mechanic...
I write technical non-fiction and find that I cannot write well without first constructing a detailed (10-20 page) outline. Are there any good outlining solutions for OSX? Apps? Templates in Micros...
I was recently asked if I was interested in writing a book for a pretty reputable publisher, which of course I accepted. I am not a writer by trade, I am a software developer with some technical wr...
I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names. My ideas are: Continuous (-ing) form: (e.g. "Creating a Cluster", "Creat...
I am preparing to publish a technical book on programming that contains figures and charts (like, compiler, linker, ASCII table, keywords list) created by myself by taking references from many sour...
In the IT industry, we often write a lot of technical documentation meant for internal use only. Those documents are often stored in an internal wiki and accessed when the need arises. The conten...
An example of the problem in an aggravated form surrounds the controversy of France changing ‘mother’ and ‘father’ to ‘parent 1’ and ‘parent 2’ in official paperwork - where the controversy suggest...
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 o...
I am wondering if how we name a version of a spacecraft differs from how we name a version of a software. For software, I usually see things like "2.0.32.32" or something like that and sometimes th...
I am working on churning out some technical documents, which are similar to a colleague's. I've copied some sections of his document as appropriate, and there are no concerns of plagiarism. His doc...
I've canceled my job to move on. Now I was asked how I want my Job description for my employment reference. My first draft was one full page... This is too much. Now I've reduced the long version ...
I've heard the term "white paper" used in many situations. I've been asked before to write white papers on different subjects, though I've never successfully completed one. I've read many different...
I'm increasingly having to write User Guides as part of my job and I need routes to make this into a more interesting exercise. Hence, I was actually looking for something completely different whe...
My background I'm a native French speaker and a software engineer, I studied in French and grew up speaking French. My Question is: which language should I use for my technical blog posts? On o...
Typically, the voice of marketing content doesn't match the voice of technical content -- marketing is trying to persuade you that you need something; technical writing is generally instructing you...
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 "B...
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 ad...
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 some...
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...
I wonder what the proper way of writing this question is: What do the data show? What does the data show?
Summary: I'm looking for a way for reviewers to comment collaboratively as close to "inline" as possible on a large HTML project. The problem in detail I work on a team that documents a large pro...
I'm at the very beginning of a blog post for Worldbuilding Stack Exchange's blog, Universe Factory, written in conjunction with an answer to a question on Worldbuilding. It's going to about astrono...
A writer can either choose to use bullets or else stick to conventional (or in certain cases non-conventional) numbering. Are there set guidelines about when to use what? Is the use of numbering pr...
Is there any widely accepted step by step method for writing a creative article in a professional manner. I want to improve my English writing skills in relation to creative article writing. I rea...
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 ...
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...
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 corre...
Often while writing a software requirement/change-request documentation, I need to include the quoted requirements descriptively, the impacted modules, the changes provided both in UI and in logic....
The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?
I currently spend a good deal of time over at Code Review and I would love to improve the quality of the reviews I write. Can you give me any insight into the structure or approach you use when wri...
