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


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

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


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

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


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

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

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

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

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



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