Hot answers tagged

31

I really like this question. I cringe to say it, but I somewhat agree about breaking grammar rules in the interest of safety. I frequently write technical emails/IT system announcements that are sent out to a large group of non-technical people and I find that if I write the emails using the same language that I'd write in my short stories, or even my ...


19

Of course you can't just ignore all basic grammar rules. For example, writing: Not cover the opening machines power be while do. obviously makes no sense to anyone, even though it's got all the right words (plus or minus a few grammatical suffixes) in there. It's just broken English. But you can totally write, say: Do not open cover while ...


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 ...


17

The label should be as short as possible without creating ambiguity. In many workplaces, the employer is required (OSHA, ISO, FDA, etc.) to train anyone who would be working in a particular area with the hazards of the environment and the equipment. The label acts as a reminder (as well as a legal obligation). Everyone in that lab knows lighting a flame ...


10

I'd say yes, but ... not if it loses clarity. Warning labels have to be concise or people won't be able to read them, or won't bother to read them. For example, a label that says "HIGH VOLTAGE" expresses the warning very briefly and concisely. Yes, it's not a complete, grammatically correct sentence. But you can write it in big letters so people can it ...


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 ...


8

The only rules you should feel free to violate are the rules about having a subject (which is implied), and possibly the trailing period of the sentence. All of the remaining rules should apply. For example, these three sentences from your examples should be logical enough for the average human. Do not open while powered on Disconnect power before ...


7

While I understand that space can be at a premium with these labels, I will always, always come down on the side of clarity. Warning labels frequently get turned into jokes precisely because the originators thought that words could be dropped. Do not open this cover while powered My thought: While the cover is powered? So as long as I unplug the ...


7

Yes, absolutely you can throw grammar rules out the window. Machine safety labels need to convey the danger clearly first and foremost. They also need to consider that the audience may not be fluent or conversant in the language at all. Grammar is largely irrelevant, and simple is always better. As example, here are a collection of safety labels from ...


7

Hi hebbo and welcome to Writers SE! Generally asking what to write is off topic, but I think this is an exception, because it is actually a common problem in writing (at least for me). It's not a naive question by a long shot; every now and then I have this same problem myself. The answer is usually to just rewrite the sentence until you get it. Try to ...


6

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, ...


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 ...


6

Rule #1 in technical documentation is: don't mislead the reader. If the command or function name begins with a lowercase letter, capitalizing it is an error -- it's not "Cat" but "cat". The Microsoft Manual of Style specifies that literal elements like this should be written with their correct case. It also calls for using text styling to offset them, as ...


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 ...


5

Not overkill at all. However, the Chicago Manual of Style is not really ideal for technical writing (and is intended as a look-it-up reference, not a cover-to-cover read). 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 ...


5

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 ...


5

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 ...


5

It depends on how formal the context is. If you're writing a short blog post about getting started with a new game, "you'll" probably won't be out of place. If you're writing a tutorial as part of the documentation set for expensive enterprise software, it's more common in my experience to avoid contractions. If your company or publisher has a style guide,...


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 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

The problem you're having is in attaching the final clause: NAME is...that helps...by rating...and helps... . When the reader gets to the "and" he's expecting it to bind to the "by" -- NAME helps by doing two things, rating and...helping. But the next word is "helps", which doesn't fit that pattern. So the reader has to mentally backtrack and ...


4

The GNU site itself treats the name of the Make utility as an uppercased word: https://www.gnu.org/software/make/ There does seem to be a convention to frequently use make (the command) where Make (the name) would seem more appropriate. The GNU Make manual seems to do this almost exclusively (https://www.gnu.org/software/make/manual/make.html) but always ...


4

I don't think there's any ambiguity in your example. You said that the fox is trying to find the rabbit, so it's the fox that finding, not the rabbit. Thus when you say "when it finds one", clearly "it" refers to the fox and "one" to the rabbit. I suppose theoretically "it eats it" could be ambiguous, but a reader would normally understand that the fox eats ...


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". It'...


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

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 ...


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 ...



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