Hot answers tagged

17

The number one thing that you have to realize about technical writing is that people do not read it for its own sake. They read it because they are trying to do something and they need more information. The writing does not need to engage or entertain because the reader is already engaged with the task. It is their engagement with the task and their need for ...


8

Your question title is very general, and your specific question is about the pervasiveness of the Oxford comma, and wanting to give up all lists because no one agrees. I suggest that "pervasive" depends on the type of writing (book, science, academic, or news) and--rather than give up on lists--you decide on your style guide and then handle exceptions to it ...


6

Consider incorporating your fine print into the body of the article. Nothing in your Fine Print section requires any special understanding of the science involved, or even a good understanding of how science proceeds. As a bonus: If you do that, you can drop the opening part of that section, which is about you, and not about the topic. If the authors' ...


6

This question touches on one of the central ideas of technical writing: topic-based authoring. Your paradigm example, "1. plug in 2. connect 3. watch." is a specimen of the "task" topic, but there are also (at least) 2 other types, namely "concept" and "reference". Adding a short concept topic describing the benefits of performing steps 1-3 would be more ...


5

When I'm editing technical documentation (and, ideally, when I'm writing it in the first place), I try to make every word earn its place. If both words in your phrases need to be there to make your point, then don't worry about it -- that's not a tic but the writing process. In the case of pairs (or larger groups) of descriptive adjectives or nouns, ...


5

Instead of "fiction" (made up) and "non-fiction" (facts) I'll use the terms "novel" and "textbook". We expect a novel, both fiction and non-fiction, to be about experience and possibly ideas, and textbooks to be about detailed information. But there are countless counter examples. For example the scholarly field of ethnology often employs first person ...


5

I am assuming that your organization does not have an official style guide, or that this is a personal project. (If you are bound by a style guide, consult it.) I am also assuming that you aren't using a semantic markup already; if you're using a DTD/schema/tool/markdown that already has a notion of "keyboard input", you'd use that unless there's a good ...


4

Don't Minimize the uncertainty, celebrate it! Sensational science reporting does not worry about details just bold headlines: 'Cell Phones Cause Breast Cancer!' Responsible reporting hedges their bets: 'Link between Cell phone usage and Breast Cancer Found.' Great reporting shows what the details mean: 'Developed nations have more cell phones and breast ...


4

I don't think the trouble lies in either choice, since neither is inherently better than the other (though some could argue that the two-sentences version has more clarity). Rather, you may want to be begin with a simple context-setting sentence. Since this is a technical document, consider first mentioning that there are several ways to approach data ...


4

A longer post can work on a blog that usually tends toward shorter posts if you take some care in structuring it. "Here are 20,000 words, plus equations" may send some people to the "back" button right off, but a five-minute introduction followed by an expansion can satisfy both audiences -- those looking for the high-level information and those interested ...


4

I would say as the two variables named c are not part of the same field. Even if technically acceptable, any form of cs is hard to read. Italics applied to only one letter, especially a round one like c are hard to spot. I changed "both" to "the two" because both invites the reader to consider two items as one, whereas here you want the reader to ...


4

I think what you are missing is that all writing tells a story. Just because there is no love story or car chase, that does not mean your technical writing is not telling a story. You are just telling the story of hooking up a Chromecast. That is actually an exciting story for people who just got a Chromecast. They are your characters! Don’t diminish their ...


4

I agree with @mbakeranalecta that the purpose of tecnical writing is not to entertain but to inform. I recall a textboook on software development that I had in college where the text was regularly interrupted with little stories about "Sally's first day as a programmer" and the like. These stories were presumably intended to liven up the text while ...


4

IANAL, but I think this would be borderline. It's arguably "fair use", and sounds like it meets the exception specifically provided in copyright law for "review and criticism". But copying an entire web page is pushing it. I'd ask for permission, and if someone says no, don't use their site. What you CAN do is, if you see something on a web site that you ...


3

I think the approach to this is to make what you write entertaining. Try to keep the style light, so you're not overwhelming the reader with facts. Use a steady build up, make the first few chapters skipable by someone who understands the field, but allows the layman to grasp the basics of where you're going. Keep the obvious stuff at the beginning, with ...


3

It seems to me to mostly depend on your target audience. Scientists of this field will want full throttle facts, General scientific types will expect to be convinced by strong backable data Interested non-scientists may relate more to argument that make sense and are logical rather than specific proof, The general skeptic reader will not trust any ...


3

Circumlocution. Locution that circles around a specific idea with multiple words rather than directly evoking it with fewer and apter words. Check the wiki article here. Update As an author, you'll sometimes want to use those either to avoid repetition (some sentences have the tendency to come out more often than you'd like), or specifically to ...


3

DevonThink. Look here: http://www.organizingcreativity.com/2015/02/digital-information-infrastructure-with-devonthink/ Also google stuff like "academic writing workflow" or "science writing workflow" or a combination of "workflow" with a specific software, either for writing (Scrivener) or citations (Zotero) -- there are quite a few blog posts where ...


3

This doesn't seem to me like a serious problem, it's just a part of your own personal writing style. Even in technical writing, you don't necessarily want to edit all individuality out of what you produce. My advice would be only to resist the impulse to add this in places where it isn't really necessary or helpful. Personally, I like your parallelism. ...


3

There's nothing confusing about the paragraph you have at the end. Given the replication rates for correlation-based studies, there no reason for the reader to believe that the study established a new insight into the effects of trans fats. A layperson shouldn't base his idea of the effect of trans fats on a single correlational study based on self ...


3

I would say write what you are capable of. If your talents are non-fiction, straight to the point works then definitely write it that way. But if you are very skilled at writing fiction stories detailing adventures or thought-provoking ideas, then do that. Personally, I would write a fiction novel detailing all the technical experience of advanced diving ...


3

Not overkill at all. However, the Chicago Manual of Style is not really ideal for technical writing. It is a good guide to general, formal writing for Americans. For a more international audience, the equivalent is The Oxford Guide to Style (a.k.a. New Hart's Rules, also published as half of Oxford Style Manual). The principal problem with Chicago is that ...


3

Using "he/his" will annoy some of your readers; using singular "they" will annoy others. And referring to a user as "it" will seem weird to most people. What I do is to write around the problem wherever possible. First off, if you're referring to the user of your API, it's better to write in second person imperative anyway -- "do this, then do that". ...


3

Wikipedia has this short list of graphical elements for interfaces that use the prevailing WIMP paradigm. https://en.wikipedia.org/wiki/List_of_graphical_user_interface_elements According to the example you've provided above, I think what you have there is a zoomable popup control or zoomable popup widget Hope this helps! Personally I've never liked ...


3

That table is not client-ready. I understand the technical terms like “dropdown” and “textarea” but those words should never be put in front of a client. Except for the rare exception who has some programming experience, at best the client will get nothing out of it, and at worst, they will have a really uncomfortable experience and resent you for it. I ...


3

You should refer to it as Figure 3. For the purposes of the text, the diagram is the part that counts. The caption and anything else are information that augments the diagram.


2

(Short) length of technical documentation is a must if that documentation is printed to accompany a product sold to an end user. You cannot sell a pocked digital camera with a five volume textbook on how to handle it. But I'm sure you have also experienced situations where the documentation was brief to the point of becoming confusing. If the documentation ...


2

It all depends. Size doesn't matter so much as what you do with it. ;) In my experience, what's been important is that the technical document serves the need of people in the organization to communicate, so that rather than asking a person to explain something, one can just look at the document. If that process is not happening as needed, or not happening ...


2

Try expanding the adjectives into more fleshed-out clauses. That will keep them from being right next to each other and creating that "X and Y" structure that you're noticing, as well as allowing you the chance to more fully explore the shades of meaning that you say is your intent. "When you speak, be sure to be clear and concise." When speaking, take ...


2

Here are two examples of how "e.g." has been used in scientific articles: In the first passage the authors explain who they excluded from their study. "e.g." is used to give examples of medication. Exclusion criteria included psychiatric or neurological conditions that could be associated with secondary bruxism, use of medications that may have an ...



Only top voted, non community-wiki answers of a minimum length are eligible