Hot answers tagged

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

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

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

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


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

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


3

Your question specifically asks for grammar, but perhaps you might consider distinguishing grammar and punctuation. Punctuation is variable for clarity, also known as typesetting, while grammar is more or less fixed. Punctuation: commas, periods, exclamation points ... Grammar: Grammar consists of the rules governing how words are put into sentences. [The ...


2

This is the beauty of the English language. It can convey a greater meaning from the individual parts even when some words are omitted, or grammar is truncated. The clue is that good warning language or brief instructions should be written so that the reader can infer the meaning. And if you look closer very often you can fill in the blanks and then you ...


2

In support of @DoWhileNot, the words "No Step" is placed on almost every airplane wing. It's bad grammar, but gets the point across to even the most basic English speaker/reader. Though, when I first read it, I was very confused... looking for faded or missing words that may have fallen off.


2

I think one significant problem boils down to this attitude tl;dr More-so a problem with the younger generations; there's a perceived coolness around not-learning. Also, reading words is more cognitive load than simply recognising a (good) pictogram or even identifying a colour. So in this case, less is more and fewer words leads to better outcomes. If ...


2

You can cast it as an early report on your beta launch, or as a preview of your forthcoming launch. Assuming that you're restricting it now so you can work the kinks out before spreading more widely, it helps to also talk about what you've learned -- we found and fixed this performance problem at scale, we discovered that this one part of our user interface ...


1

There really is no convention for indicating the end of things in text. You are asking for a way to move up the hierarchy of the document without a title to indicate the change. There really isn't a reliable way to indicate that to a reader. Titles indicate the beginning of things not the end of things. What there is a convention for is creating a ...


1

I think you need to join them into a single step, or else there is a risk that the user will do the first step without paying attention to the indicator arm, and may thus hold the input vane open too long. And I presume that there is a third step here, which is to close the input vane when the indicator arm reaches the set value. You definitely need to ...


1

Maybe this will work. Approximately 70% of small businesses in the United States struggle to hire qualified employees. Almost 50% of those small businesses cite lack of skills of potential employees as the reason jobs go unfilled. Filling those jobs with appropriately trained candidates is our focus.


1

"Doors to manual and cross check" Good example of brevity, IMO. The instruction is not supposed to replace the cabin crew training course, nor explain aircraft operations to passengers, but to remind the target audience (the cabin crew) with a few essential words what they need to do.


1

I would say that the newest, and in my view most promising, trend in in the use of lightweight markup languages, specifically Markdown, reStructuredText, and ASCIIDoc. Both commercial WYSIWYG tools like FrameMaker and XML vocabularies like DocBook and DITA require complex and somewhat cumbersome editors and tend to clutter the writing experience with ...



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