Recomendados
Más contenido relacionado
Similar a Writing for Developers: Some Rational Techniques (YUIConf 2012)
Similar a Writing for Developers: Some Rational Techniques (YUIConf 2012) (20)
Último
Último (20)
Writing for Developers: Some Rational Techniques (YUIConf 2012)
- 2. WRITING FOR DEVELOPERS SOME RATIONAL TECHNIQUES
- 3. WHO AM I? Technical writer for nearly fifteen years, now working as a frontend engineer (gulp!) @evangoer || evan@goer.org Author of the YUI 3 Cookbook, available in fine stores everywhere!
- 4. This talk is about tools and style. Mostly style.
- 5. This is not a grammar lecture. Ce n'est pas une conférence de grammaire.
- 6. OVERVIEW I. Tools that Don’t Suck II. English is Hard, Let’s Go Shopping! III. Separating Out Unhelpful Advice IV. Clarity: Finding Characters and Actions V. Emphasis: Topic and Stress
- 7. ―Any correction of the speech or writing of others will contain at least one grammatical, spelling, or typographical error.‖ — McKean’s Law
- 8. PART I TOOLS THAT DON’T SUCK
- 9. WHAT TO LOOK FOR FEATURES ANTI-FEATURES Plain text, hackable Proprietary, binary Multiple output formats HTML-only Rich semantics Presentational Code proximity!! Siloed --server mode WYSIWYG Gross, ugly HTML <frame>s (seriously, why?)
- 10. PART II ENGLISH IS HARD, LET’S GO SHOPPING!
- 11. ENGLISH IS A MÉLANGE Old English Latin French Fearlessness, Tenacity, Bravery, Guts… Fortitude… Mettle, Valor …
- 12. ―English is a language that lurks in dark alleys, beats up other languages, and rifles through their pockets for spare vocabulary.‖ — Author Unknown
- 13. ―English is the PHP of spoken languages.‖ — Me
- 14. TYPE I ERRORS: BASIC SYNTAX English has basic structural rules that we can all agree on, like ―Subject – Verb – Object.‖ Don’t worry about Type I Errors. You won’t make them.
- 15. TYPE II ERRORS: UNEDUCATED USAGE ―I should have knowed that.‖ Don’t worry about Type II Errors. You won’t make these errors either, unless you’re still learning English.
- 16. TYPE III ERRORS: NITPICKERY ―To boldly go where no one has gone...‖ ―To go boldly where no one has gone…‖ Don’t worry about Type III Errors. These aren’t actually errors, and it’s not worth your time trying to please people who think that these errors are real.
- 17. At best, worrying about grammar and usage is a form of premature optimization.
- 18. WHO IS YOUR AUDIENCE? DEVELOPERS, DEVELOPERS, WILLIAM SAFIRE DEVELOPERS, DEVELOPERS
- 20. THE WORLD IS FULL OF WRITING ADVICE
- 21. “BE CLEAR” A platitude. Equivalent to, ―Hit the ball squarely.‖ I already know that! But I don’t know how to hit the ball squarely.
- 22. “OMIT NEEDLESS WORDS” Another platitude. And as a bonus, a tautology! Equivalent to, ―Omit words that should be omitted.‖
- 23. “WRITE SHORT SENTENCES” Equivalent to, ―Write short programs.‖ All things being equal, a short sentence is better than a long one. But all things are never equal. There is nothing wrong with a long sentence if that sentence does its job effectively.
- 24. “AVOID ADJECTIVES AND ADVERBS.” Famous quote from Strunk & White, “Write with nouns and verbs, not with adjectives and adverbs.” Adjectives + adverbs are ~13% of English prose.1 There is no escape. [1] http://infomotions.com/blog/2011/02/fo rays-into-parts-of-speech/
- 25. SO HOW DO I WRITE GOOD BETTER? 1. Clarity – cleanup at the local sentence level 2. Cohesion and Emphasis – stringing together sentences effectively 3. Coherence – constructing elegant paragraphs, passages, and ultimately documents Today we will partly explore (1) and (2). (3) is Sir Not Appearing in this Presentation.
- 26. PART IV CLARITY: FINDING CHARACTERS AND ACTIONS
- 27. A nominalization is an abstract noun derived from a verb or adjective. initialize → initialization minify → minification elegant → elegance
- 28. Easy win: find and eliminate nominalizations and other flabby abstract nouns. Makes sentences shorter (yay) Makes your writing more concrete Clarifies who or what is acting
- 29. USING OUR POWERS FOR EVIL, NOT GOOD ―The Architecture Team’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core BCP guidelines.‖
- 30. FIND THE ABSTRACT NOUNS ―The Architecture Team’s proposal would provide for individual engineering team certification of the resilience of any new applications that were requested for exemption from core BCP guidelines.‖
- 31. CONVERT ABSTRACT NOUNS INTO CONCRETE VERBS AND ADJECTIVES ―The Architecture Team proposes that when individual engineering teams ask us to exempt new applications from core BCP guidelines, the team must certify that the technology is resilient.‖ (Still not great, but an improvement)
- 32. ENGLISH PROSE READS CLEARLY WHEN 1. The subjects of the sentences name the cast of characters. 2. The verbs for those subjects name the crucial actions of those characters. FIXED Subject Verb Object VARIABLE Characters Action --
- 33. CHARACTERS AND AGENTS Singular Agents Tilo Mitra explored YUI behavior in Windows 8. Collective Agents YUI engineers tested YUI on Windows 8. Instrumental Agents Studies of YUI performance reveal these figures. When we study YUI’s performance, we find these figures.
- 34. REVEAL THE MISSING CHARACTERS! In the last sentence of the In the last sentence of the YUI keynote address, there YUI keynote address, Dav is a rallying cry for the Glass rallied his audience to continuation of the struggle continue the struggle for for better apps. better apps. Determination of policy The vice president occurs at the vice determines policy. presidential level.
- 35. BAD NOMINALIZATIONS: EMPTY VERBS I If the nominalization follows an empty verb, then change the nominalization to a verb that can replace the empty verb ―The team has an expectation that it will ship on the deadline.‖ ―The team expects to ship on the deadline.‖ FIXED Subject Verb Object VARIABLE The team has expectation VARIABLE The team expects deadline
- 36. BAD NOMINALIZATIONS: EMPTY VERBS II If the nominalization is the subject of an empty verb, then change to a verb and find a new subject. ―Our discussion concerned improving YUI Attribute performance.‖ ―We discussed improving YUI Attribute performance.‖ FIXED Subject Verb Object VARIABLE discussion concerned performance VARIABLE we discussed performance
- 37. BAD NOMINALIZATIONS: “THERE IS” If the nominalization follows a ―There is,‖ then change to a verb and find a better subject. ―There was considerable degradation of the hardware due to the high humidity.‖ ―The high humidity considerably degraded the hardware.‖ FIXED Subject Verb Object VARIABLE degradation of was hardware VARIABLE humidity degraded hardware
- 38. GOOD NOMINALIZATIONS Abstract nouns aren’t 100% evil. They exist in the language for a reason. Use them to refer to: A wordy noun or concept in the previous sentence. ―This decision can lead to costly consequences.‖ An often-repeated concept / well-known jargon: ―Separation of concerns.‖ ―Taxation without representation.‖
- 39. PART V EMPHASIS: TOPIC AND STRESS
- 40. TOPIC The topic is the ―psychological subject.‖ What is this sentence actually about? Readers expect the topic of the sentence to correspond with the grammatical subject. FIXED Topic Stress VARIABLE ?? ?? FIXED Subject Verb Object VARIABLE Characters Action --
- 41. STRESS When reading English sentences, your voice naturally rises and falls at the end. Stress. Known information should be at the beginning; new information should be at the end, to be stressed. FIXED Topic Stress VARIABLE Old Information New Information FIXED Subject Verb Object VARIABLE Characters Action --
- 42. MOVE OLD INFO TO THE BEGINNING … which exceeded even … which exceeded even our most pessimistic our most pessimistic forecasts. The failure of forecasts. At the heart of management to halt the problem lies rising CapEx costs lies at management’s failure to the heart of the halt rising CapEx costs. problem.
- 43. STRESS NEW INFO AT THE END No one can explain No one can explain in a how magnets work in few words how a few words. magnets work.
- 44. STRESS NEW INFO AT THE END, REDUX Creating YUI synthetic Another way to support events is another way mobile devices is to to support mobile create YUI synthetic devices. Synthetic events. Synthetic events can … events can …
- 45. USING PASSIVES FOR GOOD, NOT EVIL … which leads to UI … which leads to UI inconsistency on tablets inconsistency on tablets and phones. Frontend and phones. These engineers familiar with the observations have been problems raised by mobile confirmed by frontend browser fragmentation engineers familiar with the have confirmed these problems raised by mobile observations. browser fragmentation.
- 46. SUMMARY TL;DR – HOW TO WRITE MORE BETTER
- 47. 1. Don’t worry about what William Safire thinks.
- 48. 2. Make sure your subjects correspond to characters and your verbs to actions. ―Determination of policy occurs at the vice presidential level.‖ vs. ―The vice president determines policy.‖
- 49. 3. Determine the topic of your sentence and make it correspond with the grammatical subject. ―The ball was thrown by Jane.‖ vs. ―Jane threw the ball.‖
- 50. 4. To stress new information, move it closer to the end of a sentence. ―No one can explain how magnets work in a few words.‖ vs. ―No one can explain in a few words how magnets work.‖
- 51. 5. ―Any correction of the speech or writing of others will contain at least one grammatical, spelling, or typographical error.‖ Remember McKean’s Law. Humility. Empathy.
- 52. FLICKR PHOTO CREDITS: CC-BY • Viking Statue by Frank Douwes • Statue of the Roman Emperor Trajan by Bruno Girin • L’Arc de Triomphe by Oliver Mallich • Women 2.0 Startup Weekend San Francisco 2011 by Adria Richards • City Island Little League ASG 105 by Edwin Martinez • zen garden by whatnot • My Jedi Book by maxxum_sky
- 53. QUESTIONS?
Notas del editor
- Welcome!
- I’m Evan Goer. You can find me most places on the web as “evangoer”, all one word, or email me at evan@goer.org.While I was writing the YUI 3 cookbook, I had the opportunity to work closely with a number of the core YUI engineers. And one thing I discoveredis that the YUI engineering team really cares about writing and documentation. Each YUI core engineer takes documentation seriously, regardless of whether writing is a skill that’s in their comfort zone or not. I really, really admire that.Documentation is a powerful way to promote a software library or product. Sometimes software has no real competition – it’s a unique and special snowflake. Or your boss or client has ordered you to use it. In that case, documentation doesn’t matter – if the docs suck, you’ll just have to push through anyway. But most of the time, you have competition. The JS world is rich with competition. There, documentation is a huge, HUGE differentiator.
- Now it’s one thing to say, “documentation is important,” but If you’re a software engineer who’s writing documentation, you have limited time and energy. So today I’m here to give you a small number of rational techniques for constructing effective documentation. These are the best techniques I know/… in that I can state them in the time alotted, and if you apply them, you’ll get a lot of bang for your buck.
- In particular, I’m not going to focus on grammar and usage – syntax, or how to construct *correct* English. That’s different from style, which is a higher level concept – how to construct clean, *optimal* English. I think that grammar and usage are not a fruitful use of your limited time and attention, and I’ll explain why as part of this talk.
- So here’s what we’re talking about today. By the end of this talk, I hope you’ll have a clearer sense of what’s important to focus on when cleaning up prose.I think that part of the reason engineers hate writing is that they see it as weird and arbitrary and irrational. All these strange rules! Coding makes logical sense (most of the time), but you have to be some kind of mystic or Zen master to be a good writer. I want to demystify writing for you. My goal today is not to disprove that writing in English is weird and irrational – because it often is. But I hope to at least convince you that it is at least LESS weird and irrational than you think it is.
- McKean’s Law is Murphy’s Law for writers and editors. I am sure you’ve noticed this law in action on the Internet.So an invocation before we get going: let us empathize with our fellow readers and writers, and above all let us not critique too harshly – the editing gods are unkind.
- I said this talk would be about tools and style. This is how important tools are compared to style: they get one slide.
- Documentation tools are a lot like coding tools. A skilled engineer can write great software using Notepad.exe. That said, don’t use Notepad.exe.Most of these features are pretty obvious. The big one, and the one I think a lot of engineers miss, is code proximity. A good documentation tool or format keeps its documentation source as CLOSE to your source code as possible. It should either live inside your code as comments (for API reference documentation) or live in a /doc directory, right next to the rest of your source. That way it’s part of your workflow. You don’t forget to update it, you can use your favorite editor or IDE on it…Sometimes people say, “We have a documentation problem. I know, let’s just put it on the wiki.” With apologies to Jamie Zawinski, now you have two problems. The big flaw with wikis and CMSes are that they are silos, away from your code. That’s very, very, very bad. Super duper bad. If you have a wiki that doesn’t have this design flaw – maybe the wiki generates itself from markdown in your source tree or whatever – then that’s fine.The other interesting feature is --server mode, which you find in yuidoc and Selleck. This is an awesome feature where you can spin up a little server and preview as you go. That, as Dav Glass might say, is HUGE. I’ve been using various doc tools, good, bad, and awful for over a decade, and –server mode is a killer killer feature. Worth the price of admission.
- Fundamentally, I think it’s hard to reason about spoken & written language. It helps if you know multiple languages or if you have specialized training in linguistics. But for most of us, language is just something we speak and write. It’s not something we process consciously very well – at least not without a lot of practice. You can know something is “wrong” in a passage without being to articulate exactly what is broken.Anyway, here we size up our enemy. Why does English suck? Why is English also kind of great? My goal here is to get into why English is less scary than you think it is, and why you might be spending too much time and energy worrying about the wrong things and trying to please the wrong people.
- English has a troubled history. Some languages are actually pretty pure. Old Icelandic is close enough to Modern Icelandic that Icelander schoolchildren can read 1000-year-old sagas without too much trouble. But Old English, which dates from the same period and is related to Old Norse and Old German, is almost incomprehensible to modern English speakers. You need special training to make much sense of it at all.That’s because in 1066, the Normans invaded England from France, killed King Harold, and took over. And that completely changed the language. Not only did French words and usage enter the mix, but as the late Medieval government developed, it also brought in Latin – the language of academia, law, religion, and elites. And there was no standardization. Dialects that people spoke out in the countryside were different from what people spoke in the cities, and what they spoke in the palaces. English became complex and bastardized.
- This quote came to me from an editor named Teresa Nielsen-Hayden, though it’s not original to her. The kind of cool thing about English is that English hasflexibility in expressing shades of meaning. At its core, English is very unpretentious – there’s no central committee that determines what “correct” English is. English rapidly absorbs new vocabulary from other languages, not just Latin, German and French, but all over the world.But this flexibility comes at a price. I have my own formulation of the quote on this slide, which is…
- I think the analogy is pretty good.Englishis ugly and inconsistent. It has strange features glued in from other languages. It has a crazy amount of “technical debt.”BUT – English is deployed widely. And if you know what you’re doing, English can even, I would argue, be elegant and powerful. Or even if you can’t quite hit “elegant” with English you can at least Get Stuff Done with English.
- So speaking roughly, I’ve divided English usage errors into three basic categories. Obviously this is a spectrum rather than rigid categories. But let’s go with it.Although English can be very chaotic, English does have some basic structural rules we can all agree on. You can’t just throw words in random order – that’s not any kind of coherent English expression. For example, we know who is doing what to whom because meaning in English depends on word order in a sentence: subject, verb, object. Or in English, adjectives go before the nouns they modify. “Blue hat,” not “hat blue” (in many European languages, it’s the other way around). To make an analogy to programming, this would be like your script not compiling or running due to a basic syntax error.The key thing is: don’t worry about these kinds of errors! You speak English. You won’t make them.
- An educated speaker recognizes wordslike “knowed” as incorrect. People who are just learning English have to struggle with these dumb and arbitrary exceptions. You could say that a lot of the exceptions are “tech debt” from previous awkward merges we discussed (Latin, German, French, …)In programming, the analogy is doing something that only a learner would do, like not ever stopping to break your code into smaller functions. It’s something that works, but it’s suboptimal. An experienced programmer wouldn’t do that. Like uneducated code, uneducated English is still understandable. Though here is the key difference: unlike uneducated programming, uneducated English is actually more logical! Don’t worry about these errors either. You probably won’t make these mistakes – unless you’re still an English learner. If you are, then honestly we native English speakers owe you a formal apology for our language kind of sucking. We’re really sorry about that.
- Finally, nitpickery.Is it okay to start a sentence with “But” or “And”? So as not to leave you in suspense – yes.Type III errors serve an important function, allowing highly educated people to further jockey for status amongst each other. The name of the game here is to invent some rule that has no root in the history of the English language. Ideally, pick a rule that’s valid in some other language like Latin -- a rule that ordinary folks AND great writers flout openly -- and flame everyone for not following it.Perfect example: splitting infinitives. “To boldly go where no one has gone before.” Supposedly should be “To go boldly” – you’ve split the infinitive “to go” with the adverb “boldly.” Who here has heard that this is bad? In fact, we see evidence in the historical record of people doing this in the 13th and 14th centuries – Middle English! Then in the mid 19th century, grammarians start complaining about this. And writing books about this. And most importantly… selling grammar books!The good news is that in the world of web development, there are no analogues whatsoever for these kinds of ungrounded-from-reality nitpicking issues. I think we as developers can all feel pretty smug about that.
- So most grammar & syntax is not something YOU should be concerned about. Either A) it’s stuff you should know (Type 1 or 2), or B) it’s stuff that you shouldn’t worry about. Even if there’s some edge case thing between Type II and Type III that’s incorrect, your time & attention would be far better spent on style (choosing and organizing your words effectively) than making professional grammarians happy.I mean, Type I, you’re solid. Even if you can’t articulate the rules, you aren’t writing sentences in random order. Type II, if you’re a native, educated English speaker, you probably won’t make many of these mistakes either. If you’re not a native speaker, you’re probably still fine. If you’re still learning – keep working on it.Type III, not worth your time to fret about. Stop doing it. Seriously, you’re only going to stress yourself out trying to impress a tiny fraction of the people. Early in my career I wasted a good chunk of my brain space memorizing rules that turned out to be not well grounded in reality. Don’t make my mistake. It’s much better to worry about real coherence than arbitrary rules.
- Another way of thinking about it: who are you writing for? Developers? Or William Safire? For those of you who don’t know, William Safire is a commentator who over several decades has written millions of words about proper English usage and grammar. Here is is getting a medal pinned on him by President George W. Bush.I guarantee you, William Safire is not going to care about your API documentation. Ever. The people in the other photo do.
- A lot of writing advice is well meaning but unhelpful.
- Who has heard, “Be Clear?” Super unhelpful. Just a platitude. Like the dad who’s telling his son or daughter to just hit the ball squarely – why don’t they get it, what’s wrong with them?Or in our world, it’s like telling a developer, “write clean code.” Well, yes.
- Another favorite “helpful” writing tip. It sounds good, doesn’t it?This one is even worse, as it’s a tautology. Which words are the needless ones, again? Well, if I knew that…
- Now we’re getting somewhere! This is some actual, kind of sort of concrete advice.And it’s still not very good. It’s like telling someone, write short programs. Yes, absolutely! We should write short programs – but sometimes the problem calls for a longer one.Likewise, there’s nothing wrong with a long sentence that does it’s job effectively. All a sentence really does is… add a slightly longer pause between clauses. Remember that early medieval manuscripts didn’t have sentences. (That was a bad thing!) Really, they were just long unbroken strings of uppercase Latin text. Sentences, paragraphs, typography, these are all things that people invented over the centuries to improve readability. So if you need a longer pause to help the reader – and often you do – great. If not – don’t force it. Otherwise you’re writing a children’s book.
- Finally, some concrete, actionable advice. This is a very famous bit from Strunk and White. Who’s read Strunk & White?(Hold up Strunk & White. Read the next sentence). That’s two adjectives, people! There is no escaping adjectives and adverbs. They are part of the language.In linguistic and professional writing circles, there are two camps about Strunk and White. The first say, “Strunk and White isn’t very good – it’s a mediocre, pretty archaic freshman comp book. Probably harmless.” The second camp says, “Strunk and White is DANGEROUS and DAMAGING PEOPLE’S BRAINS and should probably be banned.” I’m in the moderate camp, camp “Harmless”. But still – if you see someone uncritically recommending Strunk and White as God’s gift to writing… you should consider questioning their other writing advice as well.
- So forget about platitudes and bad advice – what can I actually do? There are three areas you can focus.The local sentence level, cleanup within a sentence.Stringing sentences together, so that they flow well, one into the otherAnd finally paragraph and document level coherence. These are all HUGE topics, so I’m going to give you a smattering of techniques for 1 and 2. 3 is right out.
- I don’t usually like introducing jargon around the language and parts of speech, but this one is worth knowing: “Nominalization.”Initialize, the verb, becomes initialization, the abstract noun.Minify, the verb, becomes minification, the abstract noun.Elegant, the adjective, becomes elegance, the abstract noun.Note that some nominalizations have the same form whether they’re an abstract noun or a verb. Like “charge” and “charge”. English is weird.
- Nominalizations are almost always bad (though they’re not 100% bad! Almost everything in the language serves some useful purpose.) The name of the game is that you nuke nominalizations. As a happy side effect, lots of other good things happen. Most important of all is that it clarifies WHO is acting, which is VERY important for understanding the sentence.
- Here I have used all my dark powers to intentionally write a very unclear, but still syntactically correct English sentence. Raise your hand when you think you understand what it’s saying.In case you’re wondering, this is an original. Invented by me, for purposes of evil -- not torn from internal corporate documents. But it totally could be.How do we fix this?
- Where are the abstract nouns? Let’s highlight them.Proposal propose (verb)Certification certify (verb). Resilience resilient (adj). Exemption exempt (verb)
- Make these changes, and the sentence almost magically unscrambles itself. As you convert abstract nouns to verbs and adjectives, you are FORCED to identify who is doing what.I converted four words, and added a fifth verb, “ask,”, to make things more clear. Read the sentence again. Does it make sense? (Flip back to the previous slide.)
- Here is a handy little table. English sentences (generally) have the structure subject, verb, object. That’s the nature of the beast, that’s the fixed part.What’s variable is what the subject and verb actually are. That’s very much under your control. Mess that up, and the sentence becomes much harder to read.
- What’s a character? They come in several flavors…Instrumental agents are tricky, they’re when the agent is an instrument of something or someone else. Common in academic prose or when citing works. You can make the actual agent appear. “WE study.”
- So the key is to reveal the missing characters. Highlight who they are and what they are doing. The keynote sentence – who is speaking? Who is he or she speaking to? Add those characters and the structure emerges. Dav Glass. The audience. It’s still not a very good sentence, but it’s a lot better because it’s at least easier to track what is happening.The policy sentence – that’s classic bureaucratese. That’s how the sentence would look if you made it clear who the character was.
- Here are some strategies for eliminating tricky nominalizations.An empty verb is a verb that doesn’t really connote a strong action. Like “has”. “The team has no expectation that it will ship on the deadline.” It’s clear who the subject is, “the team,” but the action is murky.So here we have a nominalization, and it’s the object of the sentence. “Has” is the weak verb that joins the subject to the object. But we can fix this. Change to “expect” – a strong concrete verb that can replace the “has”. Now the action is clear. And the sentence is shorter.
- Same problem, an empty verb, but now what if the nominalization is in the subject, rather than the object? Here the object is the same (YUI Attribute performance), but we’re going to fix up the subject. Discussion becomes the verb discussed. Then we find a new subject – who is it? We.
- Little bit of a special case, a nominalization that follow, “There is,” or some variation. Here the solution is basically the same as the previous slide. Leave the object alone. Convert the nominalization and find a better subject. The humidity. Degraded. The hardware. Boom.
- As experienced engineers, you should be really suspicious of black-and-white rule. “You must NEVER do X” or “You must ALWAYS do Y.” There are very few aspects of the language I’m aware of that are totally 100% useless. Most of the time you do want to eliminate nominalizations, but they are a handy tool.
- “The dog fetched the stick.” What is the sentence about? It’s about a dog (who is a character) – not really about a stick. The stick is what the dog is acting on.The dog is a topic. What the sentence is “about.” Readers of English expect the topic to be in the sentence’s subject. Now it’s easy to rearrange that sentence. “The stick was fetched by the dog.” But this makes the sentence more confusing – the sentence means exactly the same thing, the topic is still “A dog.” But now the dog (the topic) isn’t in the grammatical subject anymore. The stick is. That’s a trick – it screws with our cognition, makes the sentence harder to read.Note that we’ve used a passive construction to rearrange the sentence. You might have heard that passives are evil. Actually they’re NOT evil. If you use them carefully, they’re a great tool. They let you trade a little increased local complexity for better sentence flow (maybe). We’ll see how this works later on.
- “The dog fetched…” what did it fetch? Don’t leave me in suspense….! Oh, the stick. Oh, good. Whew!When you read English, your voice rises and falls at various places, but typically your voice rises and falls a bit at the end of a sentence. That’s stress. People expect information that’s new, perhaps surprising, perhaps interesting, to be stressed.So new and surprising info should go at the end. Here’s something I just talked about… and now let me reveal something a little new. This allows you to create a chain of sentences. Old, new, old, new, old, new… This creates a rhythm that’s easier for people to process. Don’t overdo it! That would make things boring. But this kind of chain is the normal happy path.
- There’s some “problem”, something to do with forecasts failing. This is presumably the thing we were talking about in previous sentences. So move “at the heart of the problem” to the beginning of the sentence. Then reveal the new info – what the root cause is – as the new, surprising info.
- Magnets, how do they work?“In a few words” is less critical, it just modifies or qualifies what we’re saying. The thing that’s more important and more interesting is the “how magnets work” part. What do people have trouble explaining…? How magnets work. Ah, okay.
- The thing that we want to stress here, the “new” information is YUI synthetic events. So put it at the end. Now you can chain this new information into a sentence where synthetic events are the topic, and you’re going to reveal something new about them…
- Check it out, we used a passive construction to make things better!On the left is active. “Engineers have confirmed these observations….” On the right is passive. “These observations have been confirmed by engineers…” I’d argue that the second is better. It flows better with the previous sentence. We were talking about some observations in previous sentences. We refer to this previous discussion by saying “these observations…” and then we reveal something new – that these results are confirmed. By engineers. Woot. But anyway, that was what we didn’t know before.Here we’ve sacrificed a small amount of local clarity (using the passive) for better flow.
- Remember: grammar, syntax, and usage are not your main problem. Making professional grammarians happy won’t do a thing for the actual clarity of your document.
- Nominalizations are your enemy here. Finding and eliminating them forces you to do all sorts of other things that clarify your prose. Your sentences will improve as if by magic!
- What is the sentence really about? It’s about Jane. Jane is doing something (throwing the ball). Put her in the subject.You can use passive constructions to rearrange sentences. Often people use passive constructions to make a sentence worse, by messing up the relationship between subject & psychological topic. Again, passives can be a useful tool, particularly if they allow you to do the opposite, aligning a subject with the topic. Or moving around old information and new information.
- Here, the interesting information is “how magnets work,” not “a few words.“ Rearrange the sentence and stress the right thing.