Posts tagged technical-writing
At this point, many languages have some "standard" format for writing documentation for individual methods. This includes, for example, Java Annotation and Microsoft's XML Documentation for .NET La...
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....
Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using Sphinx, reStructuredText, Adobe Illustrator, and Visio. Specific things we n...
We have a tool that we cannot replace that does not support single sourcing. As a result, with instructions that involve the same node, we either repeat the same dozen steps over and over, or refer...
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? A...
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?
As part of some research I am doing on measuring documentation quality, I have come across the terms "accurate" and "believable" as two separate dimensions of information quality. But the differen...
Summary Starting from the position that -- with modern web delivery -- the line between technical communication and marketing content is fading (as all the content is available to business and tec...
I am writing the release documentation for a software product and a design flaw has been discovered after the code has been frozen. Does the documentation describing this issue change if the produc...
The deadline is looming and someone realizes the product can't be shipped without documentation. Once the product leaves the remit of the software engineers (who obviously only ever write wonderful...
In a procedure, when describing a UI component, we use the bold font to represent UI components. We also match the text with the letter case of the UI component. But do we need to match the font st...
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 partic...
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 fo...
I read many articles on-line, but cannot understand where to draw the line between expository and argumentative writing. According to many articles, expository writing presents information. Argumen...
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 se...
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 ...
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 form...
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. B...
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!
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, e...
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 ...
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 metaph...
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 wr...
In the book What If?, the author usually write the unit as kilometer, atmosphere, megawatt instead of km, atm, MW. However he does use the symbols in the drawings: In one line both mm and millim...
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 ...
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 peop...
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 k...
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 ora...
So a little while ago someone said that I'll never be able to write on a native level because I wasn't born in the UK or America. I did, however, go to elementary school in the US at the ages of 5-...
I have to further explain my intent here. I'm writing down some procedures in operating manuals and servicing manuals. I mostly use numbered lists and sometimes just bulleted lists. Recently I star...
I want to rewrite my sentence in technical writing style. Could you help me rewrite my sentence? Thank you in advance The proposed methods has 4 variables need to update in a optimization proce...
My question is similar to this one, but with (hopefully) a clearly defined use case: sharing and reviewing basic tech docs with a minimal, intuitive GUI. I'm producing technical documents using MS...
I currently have the prospect of writing a considerable amount of technical documentation (describing interactions with an extremely complex online service). I consider myself a reasonably proficie...
While writing some documentation I stumbled upon the need to describe the location of a field in a Mongo Collection on one of our corporate servers. After spending a bit of time on this I arrived ...
I am writing my thesis. and I need to know the correct way of putting the reference. for example: this is a sentence taken from someone [2]. this is a sentence taken from someone[2]. ...
Excuse me if I am on the wrong StackExchange site. I write about Physics in English and typeset that with LaTeX. So I have a variable c, and there are two of them in the same expression. I want to...
I volunteer as an editor for the Mozilla Developer Network (MDN), an organization that creates free open source software such as the Firefox browser. MDN has a large number of technical topics awai...
I have been asked to write a report on the company I am working at during a placement from University (I am on an engineering programme). There was not much guidance given on what the content of th...
The oxford comma is the second comma in the sentence I like the colors red, white, and blue. Every grammar textbook I've ever seen, as well as the major style guides, feels that this is "proper" de...
In the text, I have, e.g. "...a major role to play in role-playing (Smith et al., 1990)." But can I use the same abbreviation in the bibliography? Smith, K. et al. 1990. Playing major ro...
What is Content Testing? Are there content testing tools available, or is content simply tested manually for quality?
We are working on a technical documentation project which includes the rewriting, modernization, restructuring, enrichment of the content. I'm doing the content rewriting and translation parts of t...
I am writing an an article to share knowledge, not novel. Usually, when you change the current topic, at the beginning of the new paragraph you would like to use some transition words such as Addit...
In writing procedural documentation, I have the choice of writing the complete step-by-step instructions with references to an appendix of illustrations, For instance: 1. Do task 1 (see Fig. 1) ...
I'm getting into non-fiction technical writing (a blog, but potentially ebook or otherwise). Often the best technical advice come from dissecting and synthesising good and bad examples from the ind...
I must write a book for the university and I am looking for software. The style that I want is like the books of O'Reilly, Apress or Packt. I need: Insert a table of contents (automatic). Divide...
I have been asked to write various technical and non-technical articles about computer usage, Windows usage (perhaps some Mac and *nix as well if they let me), Windows repair, and various other tec...
Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screenshots when the graphi...
Whilst writing technical documentation, there is commonly a section on troubleshooting or frequently asked questions. I know a FAQ should be real questions - not ones the publisher thinks might b...
This came up when I was writing my thesis: Usually it is recommended that when writing a thesis, one sticks to passive voice and use sentences that read like "The study showed the effect that blah...
