Posts tagged technical-writing
Our ~1500-page documentation set contains numerous screen shots and related graphics (schematics, flow diagrams, etc). Sometimes the user interface changes and we have to update all the affected g...
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...
I am writing a technical documentation about a product. Now problem is there are many interrelated and interdependent concepts. I am just confused how to put them in order. I mean if I talk about f...
I'm currently in the process of expanding my company from doing coding & web development to more technical writing and freelance tech journalism. Although my background is mainly in technology,...
In academic writing, several articles on the topic of writing papers denounce the practice of "announcing" the topic. As an example, if a paper were to read... The goal of this study is to not...
So if I later refer to figure 2 (i) or figure 2 (ii) would it be better for the figure to be labelled as is Figure 2: Figure (i) shows cycle C? or Figure 2: (i) shows cycle C or Figure 2: ...
I would love to have essays reviewed both in terms of quality writing and in terms of its content. I have researched a few sites but this service does not seem to exist.
I am trying to write a non-fiction book about summarizing core computer science concepts. I plan to self publish this book through the Amazon Kindle Direct Publishing program. My target audience in...
My question is simple: do writers need a business bank account? Or can they use a regular account for saving and declaring tax on their earnings? Further, do writers need to declares themselves a...
Good time of the day, community! Hope, that my post won't irritate too much, but rather will be helpful for someone in future. I already made some progress myself (I mean some raw unfinished vers...
I often see place or species names shortened in scientific journal articles and would like to know what the correct protocol is. Can I shorten "Gough Island" to just "Gough"? Or "leatherback turtle...
I'm having trouble finding and sticking to one word to indicate whatever value the user intends to use with my instructions. For example: Select your preferred printer. I'm wondering what s...
https://en.wikipedia.org/wiki/Tab_(interface) I have made a medical record application that allows someone to record data about someone, but the application also allows us to add the data of a rel...
When writing an error prompt, should we end the sentence with a exclamation mark or a dot? I am writing an application for iPhone and I have some error prompt in my application like "Your password...
Inspired by this question: Is there a need for better software for writers? I have an IDE¹ related question about software that can assist writers. Is there a tool to (easily) turn technical wri...
I am trying to create documentation for an application, and it's for end users who use keyboard (not mouse) and a screen reader. Some of our conventions require us to always use the full phrase ...
Essentially, I want to change: Managing a lot of people is a very difficult problem to: Lot of people, difficult problem I understand that when you shorten a title, it will become more vagu...
In my text, I have a footnote (6 or 7 lines) that is meant to be an extra insight. It does seem, however, to be a bit large for a footnote. On the other hand, if I try to place it inside the text...
Is there a way to make sure that what we write sounds consistent with the style adopted by the majority of editors? I am not sure how people do it, but almost all articles seems to have been writte...
What is the word commonly used in statistics when the thing that you want to measure cannot be (or was not) measured directly, so you assume that another thing that can be (or was) measured gives a...
Recently, I started writing articles about different subjects I learn on my own (programming, logic ...etc). While writing, I have this tendency to overexplain, I know that readers are smart, but ...
I am reviewing some research reports and found myself diving into the black hole of technical writing style. My question is what is the best way to write numbers in millions? I am not writing a n...
I'm writing a technical book (step-by-step sort of book) and noticed that all my summaries start with 'In this chapter we ...'. What would be some other sentence starters that I could use to make t...
It is common to omit end-dots in lists with very short items: Shop list: * Milk * Bread * Probably eggs It is common to use end-dots in lists with long descriptive items: Things which should b...
I am working on a technical book teaching users how to analyse data using geographic information systems. I would like to use data from an open source data portal such as open source fire departmen...
I received data for data analysis for my Bachelor-Thesis. I still got 4 weeks left to finish the 40 pages and after having gotten all my results, my supervisor and I realized that the data that I r...
I'm trying to understand the technical difference between DITA and S1000D. Yes, I know, the common wisdom is that if you need documentation for helicopter or submarine, you should use S1000D, and ...
What is the difference between "topic-based authoring" and "modular authoring"? As I know, there are two well-known authoring approaches: Narrative authoring; Topic-based authoring (see link abo...
I won't edit this question, so you can see how much I use it. The current count is 3 times. I've been told that the solution is to revise, revise, revise, but is there a particular strategy for edi...
Good day, I have the following sentence: Nowadays to reach the mass audience, you don't have to rely on traditional media. Instead, you can embrace social networks such as live video strea...
I am writing a thesis and I frequently find my self using the phrase 'is that'. For example: "The other feature that has been neglected is that the expert system would ..." I have been told that ...
I'm an engineer. At my company, engineers seem to spend a lot of time reviewing technical documentation written by people who work in different offices and time zones. Part of the reason we spend...
I am writing my bachelor's thesis in software engineering. It is split into two parts: a theoretical part where I analyze existing literature, compare models and draw conclusions; and a part where ...
I've been writing a book that has a fair share of geometric diagrams and equations. However, I am unable to make use of a computer for this and have been maintaining a journal where I manually draw...
For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more gr...
I feel bored to have this in my all mails 'Please let me know if any questions/comments', any best alternate sentence would be helpful for me
I work with a software product that has over 10 major components. The administration of most of these is done with the root user with one notable exception where they use a less privileged user for...
I work on developer documentation at a tech startup. As of now, we implement the following feedback mechanisms: We have a thumbs-up/down feedback system on each page of the docs site. If a user c...
It's well known that live presenters are often advised to add a dose of humour in order to engage the audience better. However, I very rarely see humour in written technical documentation; this de...
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...
