Posts tagged technical-writing
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. Let's see an example: Section: "Bus" A bus was very popular and chea...
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 consis...
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 a...
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, w...
I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such...
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,...
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...
Does a technical writer need a technical background?
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 working on a magic system that works with weaving types of power. The most commonly used power source is a magical code. I'm trying to base this code off of latex. LaTeX is a math code that is ...
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...
As technology advances and workflows are streamlined, some have turned to automated tools such as Doxygen, Sphinx, Swagger, etc. in order to generate technical documentation automatically. What ar...
In our documentation, we write binary numbers like this: 1010 But we write hexadecimal numbers like this: 0xABAB Now, according to the GCC compiler conventions: Numbers are normally written in...
Are they "if-else statements" or are they "if/else statements"? I'm partial to the latter, but I can see the logic of the former - both "if" and "else" are acting as a unit modifier for the noun "s...
Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general than the original definition. REST is a good example of this. While REST refe...
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...