Comment by zschuessler | Hacker News Reader

Comment by zschuessler | Hacker News Reader

These tips were centered around simplification, and they are good tips. For documentation and technical writing in particular, I picked up a few mannerisms that I now use every time I write.

The biggest impact has been to have a goal of limiting a paragraph to 2-3 sentences. From this goal my other writing traits came naturally.

When starting a paragraph, start off with a blunt statement that summarizes the paragraph. Following sentences can back up the summary sentence.

Use a short single-sentence paragraph to make an emphatic point.

Do word qualifiers add to your content? Many times not. Humans add qualifiers and adjectives more than what's necessary to understand a concept.

Readers get bored with monotony. If there's a wall of text, that's boring. If there's a wall of images, that's boring too. I try to break up a document into different types of formatting. Lists, headings, quotes, and image/content sections to make things visually appealing.

These are only goals! Sometimes a big honkin' paragraph is just what the doctor ordered.

Fun language or a well-timed joke keeps things interesting. They can give the reader a well-deserved break. Like the big honkin' paragraph usage above.

Lastly, the presentation of the content is important. Medium got their content width, font size, and colors down well. GitHub did a great job, too.

I learned to do this when a publisher took red ink to a tutorial I wrote. They gave me the goal of shortening all paragraphs to 2-3 sentences. It was tough at first but now I'm a fan. It's a fun writing exercise :-)

IMO, this style is most effective on a screen, and on a phone screen at that. This style does not fare well on the page, nor if you're trying to write on a complicated subject. It has the unfortunate feeling of superficiality. Many ideas or points require more than 2 or 3 sentences of explanation. And some ideas require many, many, sentences to present and explain. Worse, too many paragraph breaks can disrupt the flow and rhythm of an argument or article and create the expectation that you are once again introducing a new idea before the last one was allowed to reach a satisfying point. What can seem more direct for the writer, can equally come across as annoying for the reader.

I also think this style is based on the incredible low expectations we now have for the ability of readers to keep their attention, but that's another argument all together. Read some Henry James and you'll see walls of text that achieve a stunning clarity all their own.

Short, standalone paragraphs are very emphatic, though, if used sparingly.

> Read some Henry James and you'll see walls of text that achieve a stunning clarity all their own.

I take it you mean his non-fiction, given the subject? I stumbled on this - I'd be happy to hear some other recommendations - this isn't prose I'd generally look for in a contemporary text that tries to teach a subject - it's too dense for that, I believe:

https://www.gutenberg.org/files/60040/60040-h/60040-h.htm#Pa...

That said, I certainly agree that telegram style can get tiresome, and even hinder communication.

Many poisons are merely too big servings of a remedy.

I was recommending Henry James in reference to readers attention spans, who often balk at the idea of reading anything quite as dense as from James' writings. But they're missing out. His famous Chp. 42 from Portrait of a Lady is the single best articulation of personal reflection on a failed marriage I have ever read - ever. [0] Losing out on that simply because it's a big imposing paragraph suggests an unwillingness to challenge oneself, which, I think at least, is only to our loss as our attention spans wane.

Specifically for non-fiction, I would recommend R.G. Collingwood, a philosopher of ordinary language who was writing in the late 1930's. His writing, like many philosophers from that time, balances depth with clarity with stunning skill. His introduction to his book "The Principles of Art"[1] is one of my favorite bits of writing ever because of just how clear it is. The paragraphs are often long, but they are meticulously edited to keep forward momentum, and a sense of dawning awareness of a problem which he is solving, present without dragging the reader down. Most of all they are calm. It never seems rushed, or forced, or over-pruned. It's a rhetorical style of instruction that only works when you incorporate length into your writing.

As an aside, the first sentence in the introduction is one of my favorite openings of all time. "The business of this book is to answer the question: What is art?"

---

[0]: http://www.online-literature.com/henry_james/portrait_lady/4...

[1]: https://books.google.ca/books?id=SXpMC9416y4C&printsec=front...

You're pulling our leg, right?

It's worth making explicit: this helps native-language readers too! Scholarly papers full of garden path sentences are mocked for a reason. Convoluted writing is hard for everyone to understand.

I totally agree. When the word "accessible" comes up, people often think of disabled people who have permanent disabilities.

That's only a subsection of how accessibility helps - there's temporal accessibility and cultural accessibility (and probably even more facets). Curb cutouts and automatic doors help people with wheelchairs. But it also helps people carrying large packages in their hands, or are riding a bike.

Similarly, accessible writing helps people who are feeling tired, are distracted, or are trying to skim the material.

> full of garden path sentences

FYI, as a non-native English speaker, I have no idea what a "garden path sentence" means.

English gardens are often designed to appear wild. A garden path wanders, showing you only a small amount of what is there at any moment. Thus a "garden path sentence" is one that wanders from one subject to another. You are meant to enjoy the experience of walking through it, not the beauty of the master plan of angles and viewpoints (as compared to most Continental gardens, like Versailles or Schoenbrunn). There are exceptions on both sides, of course.

But the point is that "garden path sentence[s]" are more random, more free and loose.

While I admire your commitment to practicing what you preach, I can't help but think that you've taken it further than it's meant to go, though in a way that's hard to place. But it feels ... abrupt. Offensively effusive. A stream of emphatic points without a break.

I respect your commitment to a particular style, but... I hate it. It feels like there's no connection between statements, just a sequence of atomized declarations. Writing that makes an argument often needs longer paragraphs. You may be limiting what you can say by the format you have to say it in.

Now that you've done the stunt for your publisher, it may be time to transcend this style.

Nice of you to practice what you preach in this comment.

It's a demonstration of the concept in action; I love this!

> I try to break up a document into different types of formatting. Lists, headings, quotes, and image/content sections to make things visually appealing.

I'm sorry, but I have to disagree. It's very difficult for me to follow textbooks that have 200 different colors and 5 sidebars per page.

You would probably like law textbooks. They are just prose, mostly with in-line citations rather than footnotes. No colored sections and only only a rare sidebar. They make reading, serious 100+ page each sitting reading, much easier. There is only one voice to follow and your eyes never need to bounce around the page.

Yes! I would absolutely love that. No guesswork as to what train of thought to follow. All textbooks should be like that.

Short paragraphs are great in an online forum. In anything else they become very difficult. And starting paragraphs with one-sentence points is a gradeschool rule. Often a two-sentence point is more effective (see above). The only universal answer to becoming a better writer is to read more. Read material from people you think are good writers. The more good writing you read the easier it will be for you to create your own. But watch/read too much british stuff, accidentally call an elevator a lift, and everyone thinks you are british spy.

> The biggest impact has been to have a goal of limiting a paragraph to 2-3 sentences. From this goal my other writing traits came naturally.

This makes your writing, including the comment I'm responding to, slower and harder to read. Paragraphs give text a higher level structure by logically grouping related sentences. Without that grouping, it's a soup of needlessly double-spaced sentences strewn across too much vertical space.

Reply on news.ycombinator.com